@hiver/skills 1.0.1

package/collections/web/skills/connect-api/references/api-call-structure.md

@@ -0,0 +1,84 @@
+# API Call Structure
+
+## For Modern Auth Fetchers (HiverNewAuthCall based)
+
+- **Use async/await pattern** with error handling that returns `[data, null]` or `[null, error]`:
+  - Applies to: `AiBifrostAuth`, `CustomFieldsService`, `AutomationService`, `HiverSlaNewAuth`, `CsatNewAuthCall`, `TagBifrostAuth`, `HiverIntegrationBifrostAuth`, `HiverChatBifrostAuth`, `HiverNotesAxios`, `OutOfOfficeService`, `CustomerPortalApiService`, `HiverNotifCall`
+  ```javascript
+  import { AiBifrostAuth } from "../../../../utils/AiNewAuth";
+  // OR any other modern auth fetcher
+  
+  const fetchData = async (param) => {
+    try {
+      const response = await AiBifrostAuth({
+        url: `/v1/endpoint?param=${param}`,
+        method: "GET", // or "POST", "PUT", "PATCH", "DELETE"
+        data: {}, // For POST/PUT/PATCH
+      });
+      return [response.data, null];
+    } catch (err) {
+      return [null, err.message];
+    }
+  };
+  ```
+
+## For createAxios based Fetchers
+
+- **Use async/await pattern** with error handling:
+  - Applies to: `AiAxios`, `HiverCustomerPortalAxios`
+  ```javascript
+  import { AiAxios } from "../../../../utils/AiAxios";
+  
+  const fetchData = async (param) => {
+    try {
+      const response = await AiAxios({
+        url: `/v1/endpoint?param=${param}`,
+        method: "GET", // or "POST", "PUT", "PATCH", "DELETE"
+        data: {}, // For POST/PUT/PATCH
+      });
+      return [response.data, null];
+    } catch (err) {
+      return [null, err.message];
+    }
+  };
+  ```
+
+## For Legacy HiverAxios
+
+- **Use async/await with try/catch**:
+  ```javascript
+  import { HiverAxios } from "h-extension-common";
+  
+  const fetchData = async (payload) => {
+    try {
+      const response = await HiverAxios({
+        url: `/api/endpoint`,
+        type: "GET", // or "POST", "PUT", "DELETE" - Note: uses "type" not "method"
+        params: payload, // Request body/params
+      });
+      return [response.data, null];
+    } catch (err) {
+      return [null, err.message];
+    }
+  };
+  ```
+
+## For HiverAnalyticsAxios
+
+- **Use async/await with try/catch**:
+  ```javascript
+  import { HiverAnalyticsAxios } from "../../../../utils/HiverAnalyticsAxios";
+  
+  const fetchData = async (payload) => {
+    try {
+      const response = await HiverAnalyticsAxios({
+        url: `/api/endpoint`,
+        type: "GET", // or "POST", "PUT", "PATCH", "DELETE"
+        params: payload, // Request body/params
+      });
+      return [response.parsedBody, null]; // Note: HiverAnalyticsAxios returns parsedBody
+    } catch (err) {
+      return [null, err.message];
+    }
+  };
+  ```

package/collections/web/skills/connect-api/references/best-practices.md

@@ -0,0 +1,10 @@
+# Best Practices
+
+- **Keep API functions pure** - separate API logic from React Query hooks
+- **Use TypeScript types** if the project uses TypeScript
+- **Add JSDoc comments** for complex hooks explaining parameters and return values
+- **Handle loading states** using `isLoading`, `isFetching` from React Query
+- **Handle error states** using `isError`, `error` from React Query
+- **Use `enabled` option** for conditional queries
+- **Use `refetchOnMount`, `refetchOnWindowFocus`** options when needed
+- **Export query keys** from hook files for use in other components

package/collections/web/skills/connect-api/references/data-fetchers.md

@@ -0,0 +1,52 @@
+# Data Fetcher Selection
+
+- **All data fetcher utilities are located in `react-extn/src/utils`**
+- **Use the appropriate fetcher** based on the service you're working with:
+
+## Modern Auth Fetchers (HiverNewAuthCall based)
+
+These use `method` (GET, POST, PUT, PATCH, DELETE) and return promises:
+
+| Fetcher | Use Case | Service | Import Path |
+|---------|----------|---------|-------------|
+| `AiBifrostAuth` | AI service endpoints | AI Service | `../../../../utils/AiNewAuth` |
+| `CustomFieldsService` | Custom fields operations | Custom Fields Service | `../../../../utils/CustomFieldsService` |
+| `AutomationService` | Automation workflows | Automations Service | `../../../../utils/AutomationService` |
+| `HiverSlaNewAuth` | SLA management | SLA Service | `../../../../utils/slaNewAuth` |
+| `CsatNewAuthCall` | CSAT surveys | CSAT Service | `../../../../utils/csatNewAuth` |
+| `TagBifrostAuth` | Tag operations | Tags Service | `../../../../utils/tagNewAuth` |
+| `HiverIntegrationBifrostAuth` | Integration endpoints | Integration Service | `../../../../utils/integrationNewAuth` |
+| `HiverChatBifrostAuth` | Chat/channels operations | Channels Service | `../../../../utils/chatNewAuth` |
+| `HiverNotesAxios` | Notes operations | Notes Service | `../../../../utils/HiverNotesNewAuth` |
+| `OutOfOfficeService` | Schedule management | Schedule Service | `../../../../utils/OutOfOfficeService` |
+| `CustomerPortalApiService` | Customer portal | Customer Portal Service | `../../../../utils/CustomerPortalApiService` |
+| `HiverNotifCall` | Notifications | Notifications Service | `../../../../utils/notificationAuthCall` |
+
+**Usage pattern for modern auth fetchers:**
+```javascript
+import { AiBifrostAuth } from "../../../../utils/AiNewAuth";
+// OR
+import { CustomFieldsService } from "../../../../utils/CustomFieldsService";
+
+const response = await AiBifrostAuth({
+  url: `/v1/endpoint`,
+  method: "GET", // or "POST", "PUT", "PATCH", "DELETE"
+  data: {}, // For POST/PUT/PATCH
+});
+```
+
+## createAxios based Fetchers
+
+These use `method` and return promises:
+
+| Fetcher | Use Case | Service | Import Path |
+|---------|----------|---------|-------------|
+| `AiAxios` | AI service (legacy) | AI Service | `../../../../utils/AiAxios` |
+| `HiverCustomerPortalAxios` | Customer portal (legacy) | Customer Portal Service | `../../../../utils/CustomerPortalAxios` |
+
+## Legacy/Custom Fetchers
+
+| Fetcher | Use Case | Service | Import Path |
+|---------|----------|---------|-------------|
+| `HiverAxios` | Legacy API calls | Default Hiver API | `h-extension-common` |
+| `HiverAnalyticsAxios` | Analytics data | Analytics Service | `../../../../utils/HiverAnalyticsAxios` |

package/collections/web/skills/connect-api/references/error-handling.md

@@ -0,0 +1,34 @@
+# Error Handling
+
+- **Handle errors in mutation hooks**:
+  ```javascript
+  import { useSnackbar } from "../../../../common";
+  import { theme } from "@hiver/hiver-ui-kit";
+  
+  const showSnackbar = useSnackbar();
+  
+  // In mutation onSuccess handler
+  onSuccess: (response) => {
+    const [result, error] = response;
+    if (error) {
+      showSnackbar({
+        message: error || "Operation failed",
+        background: theme.palette.red.primary,
+      });
+      return;
+    }
+    // Handle success...
+  },
+  
+  // In mutation onError handler (for unexpected errors)
+  onError: (error, variables, context) => {
+    showSnackbar({
+      message: error.message || "Operation failed",
+      background: theme.palette.red.primary,
+    });
+    // Rollback optimistic updates if needed
+    if (context?.previousData) {
+      queryClient.setQueryData([API_QUERIES.resource], context.previousData);
+    }
+  }
+  ```

package/collections/web/skills/connect-api/references/hook-organization.md

@@ -0,0 +1,11 @@
+# Hook Organization
+
+- **Always create separate custom hooks** for querying and mutating server data
+- **Place hooks in a `hooks` folder** within the module/component directory
+  - Example structure: `react-extn/src/AiCopilot/Pages/Chat/hooks/` or `react-extn/src/AiCopilot/Pages/Tags/hooks/`
+- **Naming convention**:
+  - Query hooks: `useGet[ResourceName].js` (e.g., `useGetChatList.js`, `useGetSuggestedTags.js`)
+  - Mutation hooks: `use[Action][ResourceName].js` (e.g., `useSendChatMessage.js`, `useApplyTags.js`)
+- **Reference examples**:
+  - `react-extn/src/AiCopilot/Pages/Chat/hooks/useGetChatList.js`
+  - `react-extn/src/AiCopilot/Pages/Tags/hooks/useGetSuggestedTags.js`

package/collections/web/skills/connect-api/references/query-keys.md

@@ -0,0 +1,21 @@
+# Query Key and Mutation Key Management
+
+- **Never hardcode query/mutation keys** directly in hook files
+- **Always define keys in a constants file** for the module
+  - Create or use existing `constants/queries.js` file in the module directory
+  - Example: `react-extn/src/AiCopilot/Pages/Chat/constants/queries.js` or `react-extn/src/AiCopilot/Pages/Tags/constants/queries.js`
+- **Naming convention**: Use descriptive constant names in an `API_QUERIES` object
+  ```javascript
+  // In constants/queries.js file
+  export const API_QUERIES = {
+    list: 'ai_chat_list',
+    send: 'ai_chat_message',
+    tagsList: 'ai_tags_list',
+  };
+  ```
+- **Include dynamic parameters** in query keys for proper cache invalidation:
+  ```javascript
+  queryKey: [API_QUERIES.list, smIdsKey, conversationId]
+  // OR for single parameter
+  queryKey: [API_QUERIES.tagsList, String(smId), String(conversationId)]
+  ```

package/collections/web/skills/connect-api/references/react-query-usage.md

@@ -0,0 +1,83 @@
+# React Query Usage
+
+## For Data Fetching (Queries)
+
+- **Use `useQuery` from `@tanstack/react-query`** for GET requests
+- **Structure**:
+  ```javascript
+  import { useQuery } from "@tanstack/react-query";
+  import { AiBifrostAuth } from "../../../../utils/AiNewAuth"; // For AI service
+  // OR
+  import { HiverAxios } from "h-extension-common"; // For legacy API calls
+  
+  // Import query keys from constants (see section 3)
+  import { API_QUERIES } from '../constants/queries';
+  
+  // API function - returns [data, null] on success or [null, error] on failure
+  const fetchResource = async (param1, param2) => {
+      const response = await AiBifrostAuth({
+        url: `/v1/resource?param=${param1}`,
+        method: "GET",
+      });
+      return response.data;
+  };
+  
+  // Custom hook
+  export const useGetResource = ({ param1, param2, enabled = true }) => {
+    return useQuery({
+      queryKey: [API_QUERIES.resource, param1, param2],
+      queryFn: () => fetchResource(param1, param2),
+      enabled: enabled && param1 !== undefined,
+      refetchOnMount: true, // Optional
+    });
+  };
+  ```
+
+## For Data Mutations
+
+- **Use `useMutation` from `@tanstack/react-query`** for POST, PUT, PATCH, DELETE requests
+- **Structure**:
+  ```javascript
+  import { useMutation, useQueryClient } from "@tanstack/react-query";
+  import { AiBifrostAuth } from "../../../../utils/AiNewAuth"; // For AI service
+  // OR
+  import { HiverAxios } from "h-extension-common"; // For legacy API calls
+  import { useSnackbar } from "../../../../common";
+  import { theme } from "@hiver/hiver-ui-kit";
+  import { API_QUERIES } from '../constants/queries';
+  
+  // API function - returns [data, null] on success or [null, error] on failure
+  const updateResource = async (id, data) => {
+    
+      const response = await AiBifrostAuth({
+        url: `/v1/resource/${id}`,
+        method: "POST",
+        data: data,
+      });
+      return response.data
+    
+  };
+  
+  // Custom hook
+  export const useUpdateResource = () => {
+    const queryClient = useQueryClient();
+    const showSnackbar = useSnackbar();
+    
+    return useMutation({
+      mutationFn: ({ id, data }) => updateResource(id, data),
+      onSuccess: (response) => {        
+        // Invalidate related queries
+        queryClient.invalidateQueries({ queryKey: [API_QUERIES.resource] });
+        showSnackbar({
+          message: "Resource updated successfully",
+        });
+      },
+      onError: () => {
+        showSnackbar({
+          message: "Failed to update resource",
+          background: theme.palette.red.primary,
+        });
+      },
+    });
+  };
+  ```

package/collections/web/skills/connect-api/references/url-placeholders.md

@@ -0,0 +1,17 @@
+# URL and Method Placeholders
+
+- **Keep placeholders** for URL and HTTP method when creating hooks
+- **Format**: Use clear comments indicating where to fill in:
+  ```javascript
+  const fetchData = async (id) => {
+    try {
+      const response = await AiBifrostAuth({
+        url: `/v1/resource/${id}`, // TODO: Update endpoint URL
+        method: "GET", // TODO: Update HTTP method (GET, POST, PUT, PATCH, DELETE)
+      });
+      return [response.data, null];
+    } catch (err) {
+      return [null, err.message];
+    }
+  };
+  ```

package/collections/web/skills/scaffold-react-feature/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: scaffold-react-feature
+description: Generate standard feature folder structure and boilerplate for new React features/modules. Internal skill — used by build-milestone agent, not invoked directly by users.
+---
+
+# Scaffold Feature
+
+**Trigger:** Only when building a **new feature or module**. Do NOT use for bug fixes.
+
+**Used by:** `build-milestone` agent internally. Not invoked directly by users.
+
+---
+
+## Step 1 — Determine Structure Needs
+
+Before creating anything, infer from the milestone/context:
+
+1. **Does the module have multiple distinct views?**
+   - Yes → use `pages/` folder + internal routing in `index.js`
+   - No → write module logic directly in `index.js`
+
+2. **How is the module consumed?** (this is the consumer's concern, not the scaffold's)
+   - As a route component somewhere in the app
+   - Directly imported inside another component
+   - Either way, the internal structure is the same
+
+---
+
+## Step 2 — Folder Structure
+
+**Only create a directory if there is real content for it.** The list below is the ceiling, not the floor. A small feature may only need `index.js`, `constants.js`, and a hook file.
+
+```
+<FeatureName>/
+  index.js           ← entry point (routing + providers, OR direct module logic if no pages)
+  constants.js       ← query keys, route paths, enums, UI strings
+  utils.js           ← pure helper functions (only if needed)
+  components/        ← shared UI components reused across pages (only if needed)
+  hooks/             ← API hooks and custom hooks (only if needed)
+  context/           ← React context + useReducer (only if local state is too complex for useState)
+  pages/             ← sub-page components (only if module has multiple distinct views)
+```
+
+Each page inside `pages/` is an independent mini-module and can recursively follow the same structure.
+
+---
+
+## Step 3 — `index.js` Patterns
+
+### With pages (routing)
+```js
+import React from 'react';
+import { Route, Switch, useRouteMatch } from 'react-router-dom';
+import Boundary from '../../common/ErrorBoundaries/Boundary';
+import { XxxProvider } from './context/XxxContext'; // only if context exists
+import XxxListPage from './pages/XxxListPage';
+import XxxDetailPage from './pages/XxxDetailPage';
+
+const Xxx = () => {
+    const match = useRouteMatch();
+    return (
+        <Boundary fallbackType="default">
+            <XxxProvider> {/* only if context exists */}
+                <Switch>
+                    <Route exact path={match.path} component={XxxListPage} />
+                    <Route path={`${match.path}/:id`} component={XxxDetailPage} />
+                </Switch>
+            </XxxProvider>
+        </Boundary>
+    );
+};
+
+export default Xxx;
+```
+
+### Without pages (no routing)
+```js
+import React from 'react';
+import Boundary from '../../common/ErrorBoundaries/Boundary';
+
+const Xxx = () => {
+    // module logic lives here directly
+    return (
+        <Boundary fallbackType="default">
+            {/* component UI */}
+        </Boundary>
+    );
+};
+
+export default Xxx;
+```
+
+---
+
+## Step 4 — Hook Conventions (`hooks/`)
+
+- **API hooks** → file named `useXxxApi.js`. Contains `useQuery` and/or `useMutation`. Both can live in the same file. API call function defined in the same file.
+- **Custom hooks** → file named `useXxx.js`. Contains business logic, derived state, orchestration.
+- No separate `api/` folder — API calls live inside the hook file directly.
+
+```js
+// hooks/useXxxApi.js
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { showMessage } from 'h-commons';
+import { HiverAxiosInstance } from '../../../common';
+import { QUERY_KEYS } from '../constants';
+
+const fetchXxxList = (params) =>
+    HiverAxiosInstance({ url: '/api/v1/xxx', method: 'GET', params });
+
+export const useXxxListApi = (id) =>
+    useQuery({
+        queryKey: [QUERY_KEYS.XXX_LIST, id],
+        queryFn: () => fetchXxxList({ id }),
+        enabled: !!id,
+    });
+
+const createXxx = (payload) =>
+    HiverAxiosInstance({ url: '/api/v1/xxx', method: 'POST', data: payload });
+
+export const useXxxCreateApi = (id, onSuccess) => {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: createXxx,
+        onSuccess: () => {
+            showMessage({ message: 'Created successfully' });
+            if (typeof onSuccess === 'function') onSuccess();
+        },
+        onSettled: () => {
+            queryClient.invalidateQueries([QUERY_KEYS.XXX_LIST, id]);
+        },
+    });
+};
+```
+
+---
+
+## Step 5 — Context (optional)
+
+Only add when local state is shared across multiple components and is too complex for `useState`.
+
+```js
+// context/XxxContext.js
+import React, { useMemo, useReducer } from 'react';
+
+const initialState = { fieldA: '', fieldB: null };
+
+const xxxReducer = (state, action) => {
+    switch (action.type) {
+        case 'UPDATE_FIELD': return { ...state, ...action.payload };
+        case 'RESET': return initialState;
+        default: return state;
+    }
+};
+
+const XxxContext = React.createContext();
+
+export const useXxxContext = () => React.useContext(XxxContext);
+
+export const XxxProvider = ({ children }) => {
+    const [state, dispatch] = useReducer(xxxReducer, initialState);
+    const value = useMemo(() => ({
+        state,
+        updateField: (payload) => dispatch({ type: 'UPDATE_FIELD', payload }),
+        reset: () => dispatch({ type: 'RESET' }),
+    }), [state]);
+
+    return <XxxContext.Provider value={value}>{children}</XxxContext.Provider>;
+};
+```
+
+---
+
+## Step 6 — Feature Flag (if needed)
+
+**1. Add key** to `modules/common/constants/featureConstants.js`:
+```js
+export const XXX_FEATURE_KEY = 'rls-xxx-feature-name'; // rls- for release, ftr- for feature
+```
+
+**2. Add checker** to `modules/common/helpers/featureKeys.js`:
+```js
+export const isXxxFeatureEnabled = (availableFeatures) =>
+    isFeatureEnabled(availableFeatures, XXX_FEATURE_KEY);
+```
+
+**3. Gate in component:**
+```js
+import { useSelector } from 'react-redux';
+import { availableFeaturesSelector } from 'h-commons';
+import { isXxxFeatureEnabled } from '../../common/helpers/featureKeys';
+
+const availableFeatures = useSelector(availableFeaturesSelector);
+if (!isXxxFeatureEnabled(availableFeatures)) return null;
+```
+
+---
+
+## Checklist
+
+- [ ] Folder created only with directories that have real content
+- [ ] `index.js` set up — routing if multiple views, direct logic if single view
+- [ ] `constants.js` created with query keys, route paths, enums
+- [ ] API hooks in `hooks/useXxxApi.js`, custom hooks in `hooks/useXxx.js`
+- [ ] `context/` added only if local state is too complex for `useState`
+- [ ] `pages/` added only if module has multiple distinct views
+- [ ] Feature flag key added to `featureConstants.js` (if needed)
+- [ ] Feature flag checker added to `featureKeys.js` (if needed)