ai-qakit 1.0.0

package/templates/.claude/commands/devkit/frontend/create-api-integration.md

@@ -0,0 +1,507 @@
+---
+description: Generate API integration layer (hooks, services, types) following project patterns
+argument-hint: [api-endpoint-or-resource]
+allowed-tools: Read, Grep, Write, Edit, AskUserQuestion
+---
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+---
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+# Create API Integration
+
+Generate API integration for: $ARGUMENTS
+
+## ⚠️ Plan Before Executing
+
+**Always create a structured plan and get user approval before making changes.**
+
+1. Analyze the request and show API integration design
+2. Display the integration structure (types, services, hooks)
+3. Show all files that will be created
+4. Ask for confirmation before writing files
+5. Never create integrations without user approval
+
+## Important: Ask for Clarification
+
+**If anything is unclear, DO NOT GUESS. Ask the user:**
+
+- "What is the base URL for this API? (e.g., /api/v1/users)"
+- "What HTTP methods are needed? (GET, POST, PUT, DELETE)"
+- "What does the response shape look like?"
+- "Should I generate TanStack Query hooks or just fetch functions?"
+- "Does this need authentication headers?"
+- "Should I include optimistic updates for mutations?"
+- "Are there any query parameters for filtering/pagination?"
+
+Use AskUserQuestion tool when you need more context before proceeding.
+
+## Step 1: Reference Project Profile
+
+Read @.claude/CLAUDE.md to understand:
+- Data fetching library (TanStack Query, SWR, RTK Query)
+- API client (fetch, axios, ky)
+- Authentication handling
+- Error handling patterns
+- Type generation approach (manual, OpenAPI codegen)
+- Service layer structure
+
+If `.claude/CLAUDE.md` doesn't exist, run `/init` first.
+
+## Step 2: Parse Request
+
+Analyze "$ARGUMENTS" to determine:
+- Resource name (users, products, orders)
+- API endpoint structure
+- Operations needed (CRUD, single operation)
+- Response types
+- Query parameters
+- Pagination requirements
+
+**Common integration types:**
+- `Full CRUD` - All operations (list, get, create, update, delete)
+- `Read Only` - Just fetching (list, get)
+- `Write Only` - Just mutations (create, update, delete)
+- `Single Operation` - One specific endpoint
+
+## Step 3: Review Existing Patterns
+
+Find and analyze existing API integrations to detect:
+- File structure (services/, api/, hooks/)
+- Naming conventions (useUsers, usersApi, userService)
+- Query key patterns
+- Error handling approach
+- Type organization
+- Base URL configuration
+
+## Step 4: Generate Types
+
+**Resource Types:**
+```typescript
+// types/user.ts
+export interface User {
+  id: string
+  email: string
+  name: string
+  role: 'admin' | 'user'
+  createdAt: string
+  updatedAt: string
+}
+
+export interface CreateUserDto {
+  email: string
+  name: string
+  role?: 'admin' | 'user'
+}
+
+export interface UpdateUserDto {
+  email?: string
+  name?: string
+  role?: 'admin' | 'user'
+}
+```
+
+**Query/Filter Types:**
+```typescript
+export interface UserFilters {
+  search?: string
+  role?: 'admin' | 'user'
+  page?: number
+  limit?: number
+  sortBy?: 'name' | 'createdAt'
+  sortOrder?: 'asc' | 'desc'
+}
+```
+
+**Paginated Response:**
+```typescript
+export interface PaginatedResponse<T> {
+  data: T[]
+  meta: {
+    total: number
+    page: number
+    limit: number
+    totalPages: number
+  }
+}
+```
+
+## Step 5: Generate API Service
+
+**With Axios:**
+```typescript
+// services/userService.ts
+import { api } from '@/lib/api'
+import type { User, CreateUserDto, UpdateUserDto, UserFilters, PaginatedResponse } from '@/types/user'
+
+const BASE_URL = '/api/v1/users'
+
+export const userService = {
+  getAll: async (filters?: UserFilters): Promise<PaginatedResponse<User>> => {
+    const { data } = await api.get(BASE_URL, { params: filters })
+    return data
+  },
+
+  getById: async (id: string): Promise<User> => {
+    const { data } = await api.get(`${BASE_URL}/${id}`)
+    return data
+  },
+
+  create: async (dto: CreateUserDto): Promise<User> => {
+    const { data } = await api.post(BASE_URL, dto)
+    return data
+  },
+
+  update: async (id: string, dto: UpdateUserDto): Promise<User> => {
+    const { data } = await api.patch(`${BASE_URL}/${id}`, dto)
+    return data
+  },
+
+  delete: async (id: string): Promise<void> => {
+    await api.delete(`${BASE_URL}/${id}`)
+  },
+}
+```
+
+**With Fetch:**
+```typescript
+// services/userService.ts
+import { apiClient } from '@/lib/api'
+import type { User, CreateUserDto, UpdateUserDto, UserFilters, PaginatedResponse } from '@/types/user'
+
+const BASE_URL = '/api/v1/users'
+
+export const userService = {
+  getAll: async (filters?: UserFilters): Promise<PaginatedResponse<User>> => {
+    const params = new URLSearchParams(filters as Record<string, string>)
+    return apiClient.get(`${BASE_URL}?${params}`)
+  },
+
+  getById: async (id: string): Promise<User> => {
+    return apiClient.get(`${BASE_URL}/${id}`)
+  },
+
+  create: async (dto: CreateUserDto): Promise<User> => {
+    return apiClient.post(BASE_URL, dto)
+  },
+
+  update: async (id: string, dto: UpdateUserDto): Promise<User> => {
+    return apiClient.patch(`${BASE_URL}/${id}`, dto)
+  },
+
+  delete: async (id: string): Promise<void> => {
+    return apiClient.delete(`${BASE_URL}/${id}`)
+  },
+}
+```
+
+## Step 6: Generate Query Hooks
+
+### TanStack Query
+
+**Query Keys Factory:**
+```typescript
+// hooks/users/keys.ts
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+  list: (filters: UserFilters) => [...userKeys.lists(), filters] as const,
+  details: () => [...userKeys.all, 'detail'] as const,
+  detail: (id: string) => [...userKeys.details(), id] as const,
+}
+```
+
+**Query Hooks:**
+```typescript
+// hooks/users/useUsers.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { userService } from '@/services/userService'
+import { userKeys } from './keys'
+import type { User, CreateUserDto, UpdateUserDto, UserFilters } from '@/types/user'
+
+// List query
+export function useUsers(filters?: UserFilters) {
+  return useQuery({
+    queryKey: userKeys.list(filters ?? {}),
+    queryFn: () => userService.getAll(filters),
+  })
+}
+
+// Detail query
+export function useUser(id: string) {
+  return useQuery({
+    queryKey: userKeys.detail(id),
+    queryFn: () => userService.getById(id),
+    enabled: !!id,
+  })
+}
+
+// Create mutation
+export function useCreateUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (dto: CreateUserDto) => userService.create(dto),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.lists() })
+    },
+  })
+}
+
+// Update mutation
+export function useUpdateUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: ({ id, dto }: { id: string; dto: UpdateUserDto }) =>
+      userService.update(id, dto),
+    onSuccess: (data, { id }) => {
+      queryClient.setQueryData(userKeys.detail(id), data)
+      queryClient.invalidateQueries({ queryKey: userKeys.lists() })
+    },
+  })
+}
+
+// Delete mutation
+export function useDeleteUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (id: string) => userService.delete(id),
+    onSuccess: (_, id) => {
+      queryClient.removeQueries({ queryKey: userKeys.detail(id) })
+      queryClient.invalidateQueries({ queryKey: userKeys.lists() })
+    },
+  })
+}
+```
+
+**With Optimistic Updates:**
+```typescript
+export function useUpdateUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: ({ id, dto }: { id: string; dto: UpdateUserDto }) =>
+      userService.update(id, dto),
+
+    onMutate: async ({ id, dto }) => {
+      await queryClient.cancelQueries({ queryKey: userKeys.detail(id) })
+
+      const previousUser = queryClient.getQueryData<User>(userKeys.detail(id))
+
+      queryClient.setQueryData<User>(userKeys.detail(id), (old) =>
+        old ? { ...old, ...dto } : old
+      )
+
+      return { previousUser }
+    },
+
+    onError: (err, { id }, context) => {
+      if (context?.previousUser) {
+        queryClient.setQueryData(userKeys.detail(id), context.previousUser)
+      }
+    },
+
+    onSettled: (_, __, { id }) => {
+      queryClient.invalidateQueries({ queryKey: userKeys.detail(id) })
+      queryClient.invalidateQueries({ queryKey: userKeys.lists() })
+    },
+  })
+}
+```
+
+### SWR
+
+```typescript
+// hooks/users/useUsers.ts
+import useSWR from 'swr'
+import useSWRMutation from 'swr/mutation'
+import { userService } from '@/services/userService'
+import type { UserFilters, CreateUserDto, UpdateUserDto } from '@/types/user'
+
+export function useUsers(filters?: UserFilters) {
+  return useSWR(['users', filters], () => userService.getAll(filters))
+}
+
+export function useUser(id: string) {
+  return useSWR(id ? ['user', id] : null, () => userService.getById(id))
+}
+
+export function useCreateUser() {
+  return useSWRMutation(
+    'users',
+    (_, { arg }: { arg: CreateUserDto }) => userService.create(arg)
+  )
+}
+
+export function useUpdateUser(id: string) {
+  return useSWRMutation(
+    ['user', id],
+    (_, { arg }: { arg: UpdateUserDto }) => userService.update(id, arg)
+  )
+}
+
+export function useDeleteUser() {
+  return useSWRMutation(
+    'users',
+    (_, { arg }: { arg: string }) => userService.delete(arg)
+  )
+}
+```
+
+### RTK Query
+
+```typescript
+// services/usersApi.ts
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
+import type { User, CreateUserDto, UpdateUserDto, UserFilters, PaginatedResponse } from '@/types/user'
+
+export const usersApi = createApi({
+  reducerPath: 'usersApi',
+  baseQuery: fetchBaseQuery({ baseUrl: '/api/v1' }),
+  tagTypes: ['User'],
+  endpoints: (builder) => ({
+    getUsers: builder.query<PaginatedResponse<User>, UserFilters | void>({
+      query: (filters) => ({
+        url: '/users',
+        params: filters,
+      }),
+      providesTags: ['User'],
+    }),
+
+    getUser: builder.query<User, string>({
+      query: (id) => `/users/${id}`,
+      providesTags: (result, error, id) => [{ type: 'User', id }],
+    }),
+
+    createUser: builder.mutation<User, CreateUserDto>({
+      query: (body) => ({
+        url: '/users',
+        method: 'POST',
+        body,
+      }),
+      invalidatesTags: ['User'],
+    }),
+
+    updateUser: builder.mutation<User, { id: string; dto: UpdateUserDto }>({
+      query: ({ id, dto }) => ({
+        url: `/users/${id}`,
+        method: 'PATCH',
+        body: dto,
+      }),
+      invalidatesTags: (result, error, { id }) => [{ type: 'User', id }],
+    }),
+
+    deleteUser: builder.mutation<void, string>({
+      query: (id) => ({
+        url: `/users/${id}`,
+        method: 'DELETE',
+      }),
+      invalidatesTags: ['User'],
+    }),
+  }),
+})
+
+export const {
+  useGetUsersQuery,
+  useGetUserQuery,
+  useCreateUserMutation,
+  useUpdateUserMutation,
+  useDeleteUserMutation,
+} = usersApi
+```
+
+## Step 7: Generate Index Export
+
+```typescript
+// hooks/users/index.ts
+export * from './useUsers'
+export * from './keys'
+
+// types/index.ts
+export * from './user'
+```
+
+## Step 8: Show Generated Files
+
+Display:
+1. All file paths to create
+2. Full content for each file
+3. Integration structure diagram:
+
+```
+┌─────────────────────────────────────┐
+│ API Integration: users              │
+├─────────────────────────────────────┤
+│ Endpoint: /api/v1/users             │
+│ Library: TanStack Query             │
+│ Auth: Bearer Token                  │
+├─────────────────────────────────────┤
+│ Generated Files:                    │
+│   - types/user.ts                   │
+│   - services/userService.ts         │
+│   - hooks/users/keys.ts             │
+│   - hooks/users/useUsers.ts         │
+│   - hooks/users/index.ts            │
+├─────────────────────────────────────┤
+│ Hooks:                              │
+│   - useUsers(filters?)              │
+│   - useUser(id)                     │
+│   - useCreateUser()                 │
+│   - useUpdateUser()                 │
+│   - useDeleteUser()                 │
+└─────────────────────────────────────┘
+```
+
+## Step 9: Usage Example
+
+```typescript
+import { useUsers, useCreateUser, useUpdateUser } from '@/hooks/users'
+
+function UsersPage() {
+  const { data, isLoading, error } = useUsers({ page: 1, limit: 10 })
+  const createUser = useCreateUser()
+  const updateUser = useUpdateUser()
+
+  const handleCreate = async (data: CreateUserDto) => {
+    try {
+      await createUser.mutateAsync(data)
+      toast.success('User created!')
+    } catch (error) {
+      toast.error('Failed to create user')
+    }
+  }
+
+  const handleUpdate = async (id: string, data: UpdateUserDto) => {
+    try {
+      await updateUser.mutateAsync({ id, dto: data })
+      toast.success('User updated!')
+    } catch (error) {
+      toast.error('Failed to update user')
+    }
+  }
+
+  if (isLoading) return <Loading />
+  if (error) return <Error error={error} />
+
+  return (
+    <UserList
+      users={data.data}
+      onUpdate={handleUpdate}
+    />
+  )
+}
+```
+
+## Step 10: Next Steps
+
+Suggest related actions:
+- Create form components: `/create-form UserForm`
+- Create table components: `/create-table UsersTable`
+- Add Storybook stories: `/create-storybook UserCard`
+- Create related pages: `/create-page users list with pagination`
+
+Generate API integration now for: $ARGUMENTS