devendra-skill-package 1.0.2

package/.github/skills/feature-generator/references/api-envelope-patterns.md

@@ -0,0 +1,327 @@
+# API Envelope Patterns Reference
+
+Used by Phase 4.6 of feature-generator to generate the DataSource class body.
+Select the pattern that matches `fingerprint.apiLib` + `fingerprint.envelopeStyle`.
+
+---
+
+## Pattern 1 — Axios + mb-operationId envelope
+
+**When**: `fingerprint.apiLib = "axios"` AND `fingerprint.envelopeStyle = "mb-operationId"`
+
+This is the most common pattern in this repository. The request body is wrapped in a
+`mb.rq.reqdata` envelope with an `operationId` field. The response is unwrapped from
+`mb.rs.resdata` by the shared Axios response interceptor before it reaches the datasource.
+
+### DataSource template
+
+```typescript
+import { apiClient } from '<fingerprint.apiClientImport>';
+import { <endpointConstantName>_ENDPOINTS } from './<screenName>Endpoints';  // screenName, not featureFolderName
+import { mockConfig } from './mockConfig';
+import type { Fetch<ScreenName>Params } from '<relative-path-to-domainRepo>';
+import mockData from '<relative-path-to-mockJson>';
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function buildEnvelope(operationId: string, reqdata: Record<string, unknown>): object {
+  return { mb: { operationId, rq: { reqdata } } };
+}
+
+export class <ScreenName>ApiDataSource {
+  async fetch<ScreenName>(params: Fetch<ScreenName>Params): Promise<Record<string, unknown>> {
+    const { <OperationId> } = mockConfig.apis;
+    if (mockConfig.<fingerprint.mockGlobalFlag> || <OperationId>.mockEnabled) {
+      await delay(mockConfig.<fingerprint.mockDelayField>);
+      return mockData as Record<string, unknown>;
+    }
+    const body = buildEnvelope('<OperationId>', {
+      // Map camelCase params to API-casing from spec requestBody
+      ApiField: params.camelCaseParam,
+    });
+    const response = await apiClient.post<Record<string, unknown>>(
+      <endpointConstantName>_ENDPOINTS.FETCH,
+      body,
+    );
+    return response.data;
+  }
+}
+```
+
+### Endpoint constant template
+
+```typescript
+// Base URL is set in the shared apiClient. Path must NOT start with '/'.
+export const <endpointConstantName>_ENDPOINTS = {
+  FETCH: 'api/v1/<service-path>/<OperationId>',
+} as const;
+```
+
+### Notes
+
+- The `buildEnvelope` function MUST use the exact field names detected in existing
+  datasource files. If the existing code uses `operationid` (lowercase i), use that.
+- `response.data` is already the unwrapped `resdata` payload after the interceptor runs.
+- `globalMockEnabled` check MUST appear BEFORE the per-API `mockEnabled` check.
+
+---
+
+## Pattern 2 — Axios + mb-operationid-lowercase envelope
+
+**When**: `fingerprint.apiLib = "axios"` AND `fingerprint.envelopeStyle = "mb-operationid-lowercase"`
+
+Some services use `operationid` (all lowercase) in the envelope AND include additional
+fields such as `reqtoken`, `appinfo`, and `deviceinfo`. Detected by reading the
+`buildEnvelope` helper (or inline envelope construction) in existing datasource files.
+
+**Detection rule**: If the existing buildEnvelope contains `reqtoken` or `appinfo` or
+`deviceinfo`, those fields MUST be included verbatim in the generated code. Do NOT
+simplify or omit them — the server will reject requests with missing fields.
+
+### DataSource template
+
+Same as Pattern 1 except the `buildEnvelope` function uses this shape:
+
+```typescript
+function buildEnvelope(operationid: string, reqdata: Record<string, unknown>): object {
+  return {
+    mb: {
+      operationid,           // lowercase 'i' — NOT operationId
+      reqtoken: null,        // always null for client-originated requests
+      rq: {
+        appinfo: {
+          appId: 'APP_ID',   // match exact key/value from detected file
+          appVersion: '1.0.0',
+        },
+        deviceinfo: {
+          deviceId: 'MOBILE-APP',   // match exact value from detected file
+          deviceType: 'MOBILE',
+        },
+        reqdata,
+      },
+    },
+  };
+}
+```
+
+### Important: always copy from detected source
+
+After detection, open the file containing the existing `buildEnvelope` and copy its
+entire function body. Do not reconstruct from memory. Differences in field names,
+casing, or nesting will cause server-side validation failures.
+
+If the envelope is inlined (not a helper function), find the `apiClient.post()` call
+and copy the entire body literal.
+
+---
+
+## Pattern 3 — Axios + no envelope (plain body)
+
+**When**: `fingerprint.apiLib = "axios"` AND `fingerprint.envelopeStyle = "none"`
+
+The request body is passed directly without any wrapper.
+
+### DataSource template
+
+```typescript
+import { apiClient } from '<fingerprint.apiClientImport>';
+import { <endpointConstantName>_ENDPOINTS } from './<screenName>Endpoints';  // screenName, not featureFolderName
+import { mockConfig } from './mockConfig';
+import type { Fetch<ScreenName>Params } from '<relative-path-to-domainRepo>';
+import mockData from '<relative-path-to-mockJson>';
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class <ScreenName>ApiDataSource {
+  async fetch<ScreenName>(params: Fetch<ScreenName>Params): Promise<Record<string, unknown>> {
+    const { <OperationId> } = mockConfig.apis;
+    if (mockConfig.<fingerprint.mockGlobalFlag> || <OperationId>.mockEnabled) {
+      await delay(mockConfig.<fingerprint.mockDelayField>);
+      return mockData as Record<string, unknown>;
+    }
+    const response = await apiClient.post<Record<string, unknown>>(
+      <endpointConstantName>_ENDPOINTS.FETCH,
+      {
+        // Flat request body — API field names from spec requestBody
+        ApiField: params.camelCaseParam,
+      },
+    );
+    return response.data;
+  }
+}
+```
+
+---
+
+## Pattern 4 — Fetch API + no envelope
+
+**When**: `fingerprint.apiLib = "fetch"` AND `fingerprint.envelopeStyle = "none"`
+
+Uses the native `fetch()` API directly. No shared client file.
+
+### DataSource template
+
+```typescript
+import type { Fetch<ScreenName>Params } from '<relative-path-to-domainRepo>';
+import mockData from '<relative-path-to-mockJson>';
+
+const BASE_URL = '<detected base URL from existing fetch calls>';
+
+export class <ScreenName>ApiDataSource {
+  async fetch<ScreenName>(params: Fetch<ScreenName>Params): Promise<Record<string, unknown>> {
+    const response = await fetch(`${BASE_URL}/<spec.apiUrl>`, {
+      method: '<spec.httpMethod>',
+      headers: {
+        'Content-Type': 'application/json',
+        // Add headers matching existing fetch calls in the codebase
+      },
+      body: JSON.stringify({
+        ApiField: params.camelCaseParam,
+      }),
+    });
+    if (!response.ok) {
+      throw { statusCode: response.status, message: `HTTP ${response.status}` };
+    }
+    return response.json() as Promise<Record<string, unknown>>;
+  }
+}
+```
+
+### Notes
+
+- Do NOT create a shared `fetch` wrapper if one does not already exist.
+- Import any auth token injection from the detected token storage utility.
+- For GET requests: omit `body`, append params as query string.
+
+---
+
+## Pattern 5 — RTK Query
+
+**When**: `fingerprint.apiLib = "rtk-query"`
+
+RTK Query uses endpoint definitions, not classes. Generate an endpoint injected into
+the existing base API slice.
+
+### Endpoint template
+
+```typescript
+// Injected into the existing base API slice detected by fingerprint.apiClientFile
+
+import { baseApi } from '<fingerprint.apiClientImport>';
+import type { <ScreenName>Item } from '<relative-path-to-domainModel>';
+import { map<ScreenName>FromDto } from '<relative-path-to-mapper>';
+
+export interface Fetch<ScreenName>Args {
+  // camelCase params from spec requestBody
+  clientCode: number;
+  sessionId: string;
+}
+
+export const <screenNameCamelCase>Api = baseApi.injectEndpoints({
+  endpoints: (builder) => ({
+    fetch<ScreenName>: builder.query<<ScreenName>Item[], Fetch<ScreenName>Args>({
+      query: (args) => ({
+        url: '<spec.apiUrl>',
+        method: '<spec.httpMethod>',
+        body: {
+          // API-casing from spec requestBody
+          ClientCode: args.clientCode,
+          SessionID: args.sessionId,
+        },
+      }),
+      transformResponse: (response: Record<string, unknown>) => {
+        const items = (response.Data ?? response.data ?? []) as Record<string, unknown>[];
+        return items.map(map<ScreenName>FromDto);
+      },
+    }),
+  }),
+  overrideExisting: false,
+});
+
+export const { useFetch<ScreenName>Query } = <screenNameCamelCase>Api;
+```
+
+### Notes
+
+- There is NO slice file for RTK Query features — the thunk/selector is replaced by
+  the generated hook.
+- Do NOT generate a separate datasource class. The endpoint builder is the datasource.
+- Do NOT generate selectors — RTK Query hooks provide isLoading, data, error directly.
+- The screen component uses `useFetch<ScreenName>Query(params)` instead of dispatching a thunk.
+
+---
+
+## Pattern 6 — React Query / TanStack Query
+
+**When**: `fingerprint.apiLib = "react-query"`
+
+React Query uses custom hooks with `useQuery` or `useMutation`.
+
+### Query hook template
+
+```typescript
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { apiClient } from '<fingerprint.apiClientImport>';
+import type { <ScreenName>Item } from '<relative-path-to-domainModel>';
+import { map<ScreenName>FromDto } from '<relative-path-to-mapper>';
+
+// <screenNameCamelCase> = camelCase of screenName, e.g. TransactionHistory → transactionHistory
+export const <screenNameCamelCase>QueryKeys = {
+  all: ['<screenNameCamelCase>'] as const,
+  list: (clientCode: number) => ['<screenNameCamelCase>', 'list', clientCode] as const,
+} as const;
+
+async function fetch<ScreenName>(params: {
+  clientCode: number;
+  sessionId: string;
+}): Promise<<ScreenName>Item[]> {
+  const response = await apiClient.post<Record<string, unknown>>(
+    '<spec.apiUrl>',
+    { ClientCode: params.clientCode, SessionID: params.sessionId },
+  );
+  const items = (response.data.Data ?? response.data.data ?? []) as Record<string, unknown>[];
+  return items.map(map<ScreenName>FromDto);
+}
+
+export function use<ScreenName>(params: {
+  clientCode: number;
+  sessionId: string;
+}): UseQueryResult<<ScreenName>Item[]> {
+  return useQuery({
+    queryKey: <screenNameCamelCase>QueryKeys.list(params.clientCode),
+    queryFn: () => fetch<ScreenName>(params),
+    staleTime: 5 * 60 * 1000,
+  });
+}
+```
+
+### Notes
+
+- There is NO slice or thunk — state comes from the React Query cache.
+- Do NOT generate selectors or Redux-related files.
+- The screen component uses `const { data, isLoading, error, refetch } = use<ScreenName>(params)`.
+- Check if the project uses TanStack Query v4 (`@tanstack/react-query`) or v3 (`react-query`).
+  The import path differs. Detect from package.json.
+
+---
+
+## Request Body Field Mapping Rules (all patterns)
+
+The spec `requestBody` uses API-casing (typically PascalCase or UPPER_SNAKE).
+The domain `Params` interface uses camelCase. The datasource maps between them:
+
+```
+Spec requestBody:             Domain Params:
+  "ClientCode": 12345     →     clientCode: number
+  "SessionID": "abc"      →     sessionId: string
+  "FamilyFlag": 0         →     familyFlag: 0 | 1
+  "PARAM1": ""            →     param1?: string
+  "FilterColumns": ""     →     filterColumns?: string
+```
+
+Always use the EXACT field names from the spec on the request side. Never rename
+API fields in the datasource — mappers and DTOs handle inbound casing, not the datasource.