opencode-agent-kit 1.0.0

package/template/.opencode/agent-docs/frontend/nuxt/API_PATTERNS.md

@@ -0,0 +1,807 @@
+# API Patterns Guide - useApi Composable
+
+Comprehensive guide untuk menggunakan custom `useApi` composable dalam project ini.
+
+## 📋 Daftar Isi
+
+1. [Overview](#overview)
+2. [Why useApi?](#why-useapi)
+3. [Basic Usage](#basic-usage)
+4. [Advanced Patterns](#advanced-patterns)
+5. [Error Handling](#error-handling)
+6. [Authentication](#authentication)
+7. [Best Practices](#best-practices)
+8. [Migration Guide](#migration-guide)
+
+---
+
+## Overview
+
+`useApi` adalah custom composable yang menyatukan `useFetch` dan `$fetch` dengan satu interface yang konsisten, plus automatic authentication dan enhanced error handling.
+
+**Location:** `app/composables/useApi.ts`
+
+### Key Features
+
+- ✅ **Unified API** - Single interface untuk GET, POST, PUT, DELETE
+- ✅ **Smart SSR/CSR** - Otomatis pakai `useFetch` di SSR, `$fetch` di CSR
+- ✅ **Auto Authentication** - Cookies forwarded otomatis
+- ✅ **Enhanced Errors** - `error.value.message` langsung accessible
+- ✅ **Auto Redirect** - 401 otomatis redirect ke login
+- ✅ **Type Safe** - Full TypeScript support dengan generics
+- ✅ **Promise-like** - Bisa di-await seperti Promise
+
+---
+
+## Why useApi?
+
+### Problem dengan Native Composables
+
+**useFetch:**
+
+```typescript
+// ❌ Auth tidak automatic
+const { data } = await useFetch('/api/users', {
+  headers: useRequestHeaders(['cookie']), // Manual!
+})
+
+// ❌ Error message susah diakses
+if (error.value) {
+  // error.value.data?.message? error.value.message? Who knows!
+  console.log(error.value?.data?.message)
+}
+
+// ❌ POST/PUT/DELETE butuh useAsyncData
+const { data } = await useAsyncData('create-user', () =>
+  $fetch('/api/users', { method: 'POST', body: formData })
+)
+```
+
+**$fetch:**
+
+```typescript
+// ❌ Tidak bisa di-await di component root
+const data = await $fetch('/api/users') // Hydration error!
+
+// ❌ No reactive state
+const loading = ref(false)
+const error = ref(null)
+// Manual state management diperlukan
+```
+
+### Solution dengan useApi
+
+```typescript
+// ✅ Simple, automatic, type-safe
+const { data, pending, error } = await useApi<User[]>('/users')
+
+// ✅ Works untuk semua HTTP methods
+const { data: created } = await useApi('/users', {
+  method: 'POST',
+  body: newUser,
+})
+
+// ✅ Error message langsung accessible
+if (error.value) {
+  console.log(error.value.message) // Consistent!
+}
+```
+
+---
+
+## Basic Usage
+
+### GET Request
+
+```typescript
+<script setup lang="ts">
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+// Simple GET
+const { data, pending, error } = await useApi<User[]>('/users')
+
+// With query parameters
+const { data: filteredUsers } = await useApi<User[]>('/users', {
+  query: {
+    role: 'admin',
+    page: 1,
+    limit: 10
+  }
+})
+
+// Reactive query
+const search = ref('')
+const { data: searchResults } = await useApi<User[]>('/users', {
+  query: { q: search },
+  watch: [search] // Refetch when search changes
+})
+</script>
+
+<template>
+  <div v-if="pending">Loading...</div>
+  <div v-else-if="error">{{ error.message }}</div>
+  <ul v-else>
+    <li v-for="user in data?.data" :key="user.id">
+      {{ user.name }}
+    </li>
+  </ul>
+</template>
+```
+
+### POST Request
+
+```typescript
+<script setup lang="ts">
+interface CreateUserDto {
+  name: string
+  email: string
+  password: string
+}
+
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+const form = reactive<CreateUserDto>({
+  name: '',
+  email: '',
+  password: ''
+})
+
+const createUser = async () => {
+  const { data, error } = await useApi<User>('/users', {
+    method: 'POST',
+    body: form
+  })
+
+  if (error.value) {
+    useToast().add({
+      title: 'Error',
+      description: error.value.message,
+      color: 'red'
+    })
+    return
+  }
+
+  useToast().add({
+    title: 'Success',
+    description: `User ${data.value?.data.name} created!`
+  })
+
+  navigateTo(`/users/${data.value?.data.id}`)
+}
+</script>
+```
+
+### PUT/PATCH Request
+
+```typescript
+const updateUser = async (userId: string) => {
+  const { data, error } = await useApi<User>(`/users/${userId}`, {
+    method: 'PATCH',
+    body: {
+      name: 'Updated Name',
+      email: 'updated@example.com',
+    },
+  })
+
+  if (!error.value) {
+    console.log('Updated:', data.value?.data)
+  }
+}
+```
+
+### DELETE Request
+
+```typescript
+const deleteUser = async (userId: string) => {
+  const confirmed = confirm('Are you sure?')
+  if (!confirmed) return
+
+  const { error } = await useApi(`/users/${userId}`, {
+    method: 'DELETE',
+  })
+
+  if (error.value) {
+    alert(error.value.message)
+  } else {
+    // Refresh list atau remove dari UI
+    users.value = users.value.filter((u) => u.id !== userId)
+  }
+}
+```
+
+---
+
+## Advanced Patterns
+
+### Manual Trigger (immediate: false)
+
+```typescript
+<script setup lang="ts">
+// Don't execute immediately
+const { data, execute, pending } = await useApi<User>('/users/123', {
+  immediate: false
+})
+
+const loadUser = async () => {
+  await execute()
+  // data.value now populated
+}
+
+// Or use in onMounted
+onMounted(() => {
+  loadUser()
+})
+</script>
+
+<template>
+  <button @click="loadUser" :disabled="pending">
+    Load User
+  </button>
+</template>
+```
+
+### Optimistic Updates
+
+```typescript
+const deleteUser = async (userId: string) => {
+  // Save original state
+  const originalUsers = [...users.value]
+
+  // Optimistic update
+  users.value = users.value.filter((u) => u.id !== userId)
+
+  // Perform API call
+  const { error } = await useApi(`/users/${userId}`, {
+    method: 'DELETE',
+  })
+
+  if (error.value) {
+    // Rollback on error
+    users.value = originalUsers
+    useToast().add({
+      title: 'Error',
+      description: error.value.message,
+      color: 'red',
+    })
+  }
+}
+```
+
+### Refresh & Refetch
+
+```typescript
+const { data, refresh, execute } = await useApi<User[]>('/users')
+
+// Refresh (same parameters)
+const reloadUsers = async () => {
+  await refresh()
+}
+
+// Execute again
+const loadMore = async () => {
+  await execute()
+}
+
+// Auto-refresh every 30s
+onMounted(() => {
+  const interval = setInterval(refresh, 30000)
+  onUnmounted(() => clearInterval(interval))
+})
+```
+
+### Dependent Requests
+
+```typescript
+// First request
+const { data: user } = await useApi<User>(`/users/${userId}`)
+
+// Second request depends on first
+const { data: posts } = await useApi<Post[]>('/posts', {
+  query: {
+    authorId: computed(() => user.value?.data.id),
+  },
+  immediate: computed(() => !!user.value), // Only fetch when user loaded
+})
+```
+
+### Polling
+
+```typescript
+const { data: status, refresh } = await useApi<JobStatus>(`/jobs/${jobId}`)
+
+// Poll every 2 seconds until complete
+const pollJob = () => {
+  const interval = setInterval(async () => {
+    await refresh()
+
+    if (status.value?.data.status === 'completed') {
+      clearInterval(interval)
+      useToast().add({ title: 'Job completed!' })
+    }
+  }, 2000)
+
+  onUnmounted(() => clearInterval(interval))
+}
+
+onMounted(pollJob)
+```
+
+### Pagination
+
+```typescript
+<script setup lang="ts">
+const page = ref(1)
+const limit = ref(10)
+
+const { data: response, pending } = await useApi<User[]>('/users', {
+  query: { page, limit },
+  watch: [page, limit]
+})
+
+const users = computed(() => response.value?.data || [])
+const total = computed(() => response.value?.total || 0)
+
+const nextPage = () => {
+  if (page.value * limit.value < total.value) {
+    page.value++
+  }
+}
+
+const prevPage = () => {
+  if (page.value > 1) {
+    page.value--
+  }
+}
+</script>
+
+<template>
+  <div>
+    <div v-if="pending">Loading...</div>
+    <ul v-else>
+      <li v-for="user in users" :key="user.id">{{ user.name }}</li>
+    </ul>
+
+    <div class="flex gap-2">
+      <button @click="prevPage" :disabled="page === 1">Previous</button>
+      <span>Page {{ page }} of {{ Math.ceil(total / limit) }}</span>
+      <button @click="nextPage" :disabled="page * limit >= total">Next</button>
+    </div>
+  </div>
+</template>
+```
+
+### Infinite Scroll
+
+```typescript
+<script setup lang="ts">
+const page = ref(1)
+const allUsers = ref<User[]>([])
+
+const { data, pending, execute } = await useApi<User[]>('/users', {
+  query: computed(() => ({ page: page.value, limit: 20 })),
+  immediate: false
+})
+
+// Load initial page
+onMounted(() => execute())
+
+// Append results
+watch(data, (newData) => {
+  if (newData?.data) {
+    allUsers.value = [...allUsers.value, ...newData.data]
+  }
+})
+
+// Load more
+const loadMore = async () => {
+  page.value++
+  await execute()
+}
+
+// Infinite scroll observer
+const sentinel = ref<HTMLElement>()
+onMounted(() => {
+  const observer = new IntersectionObserver((entries) => {
+    if (entries[0].isIntersecting && !pending.value) {
+      loadMore()
+    }
+  })
+
+  if (sentinel.value) {
+    observer.observe(sentinel.value)
+  }
+
+  onUnmounted(() => observer.disconnect())
+})
+</script>
+
+<template>
+  <div>
+    <div v-for="user in allUsers" :key="user.id">
+      {{ user.name }}
+    </div>
+    <div ref="sentinel" class="h-4" />
+    <div v-if="pending">Loading more...</div>
+  </div>
+</template>
+```
+
+---
+
+## Error Handling
+
+### Basic Error Handling
+
+```typescript
+const { data, error } = await useApi<User>('/users/123')
+
+if (error.value) {
+  // error.value.message is always accessible
+  console.error(error.value.message)
+
+  // Show user-friendly message
+  useToast().add({
+    title: 'Error',
+    description: error.value.message,
+    color: 'red',
+  })
+}
+```
+
+### Error Types
+
+```typescript
+interface ApiErrorResponse {
+  status?: boolean | string
+  message?: string // Always present
+  data?: unknown // Additional error data
+}
+
+// Usage
+const { error } = await useApi('/users')
+
+if (error.value) {
+  console.log(error.value.message) // "User not found"
+  console.log(error.value.status) // false
+  console.log(error.value.data) // Additional error context
+}
+```
+
+### Global Error Handler
+
+```typescript
+// Create composable for consistent error handling
+export const useApiError = () => {
+  const toast = useToast()
+
+  const handleError = (error: Ref<ApiErrorResponse | null>) => {
+    if (!error.value) return
+
+    const message = error.value.message || 'An error occurred'
+
+    // Log to monitoring service
+    if (import.meta.client) {
+      console.error('API Error:', error.value)
+      // trackError(error.value)
+    }
+
+    // Show toast
+    toast.add({
+      title: 'Error',
+      description: message,
+      color: 'red',
+    })
+  }
+
+  return { handleError }
+}
+
+// Usage
+const { data, error } = await useApi('/users')
+const { handleError } = useApiError()
+
+watch(error, () => handleError(error))
+```
+
+### Retry Logic
+
+```typescript
+const maxRetries = 3
+let retryCount = 0
+
+const { data, error, execute } = await useApi<User[]>('/users', {
+  immediate: false,
+})
+
+const fetchWithRetry = async () => {
+  while (retryCount < maxRetries) {
+    await execute()
+
+    if (!error.value) {
+      retryCount = 0
+      return
+    }
+
+    retryCount++
+
+    if (retryCount < maxRetries) {
+      await new Promise((resolve) => setTimeout(resolve, 1000 * retryCount))
+    }
+  }
+
+  // Max retries reached
+  useToast().add({
+    title: 'Failed after 3 retries',
+    description: error.value?.message,
+    color: 'red',
+  })
+}
+
+onMounted(fetchWithRetry)
+```
+
+---
+
+## Authentication
+
+### Automatic Cookie Forwarding
+
+```typescript
+// ✅ Cookies automatically forwarded on SSR
+const { data } = await useApi<User>('/me')
+
+// No manual header management needed!
+// useApi handles:
+// - Server: useRequestHeaders(['cookie'])
+// - Client: credentials: 'include'
+```
+
+### 401 Auto-Redirect
+
+```typescript
+// If API returns 401, useApi automatically redirects to:
+// - /cms/auth/login (for /cms/* routes)
+// - /auth/login (for other routes)
+
+// No manual redirect logic needed!
+const { data } = await useApi<User>('/protected-resource')
+// If unauthorized, user is redirected automatically
+```
+
+### Custom Auth Headers
+
+```typescript
+// For Bearer token authentication (if needed)
+const token = useCookie('auth_token')
+
+const { data } = await useApi<User>('/users', {
+  headers: {
+    Authorization: `Bearer ${token.value}`,
+  },
+})
+```
+
+### Skip Auto-Redirect
+
+```typescript
+// Prevent auto-redirect on specific pages
+// Already handled in useApi for public pages:
+const publicPages = [
+  '/cms/auth/login',
+  '/blog',
+  '/services',
+  '/about',
+  // etc.
+]
+
+// If you need custom handling, use try-catch
+const { error } = await useApi('/protected')
+
+if (error.value && error.value.status === 401) {
+  // Custom 401 handling
+  showLoginModal()
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Always Use Type Generics
+
+```typescript
+// ❌ Bad - No type safety
+const { data } = await useApi('/users')
+
+// ✅ Good - Type safe
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+const { data } = await useApi<User[]>('/users')
+// data.value?.data is now typed as User[]
+```
+
+### 2. Handle Errors Gracefully
+
+```typescript
+// ❌ Bad - Ignore errors
+const { data } = await useApi('/users')
+
+// ✅ Good - Always check errors
+const { data, error } = await useApi('/users')
+
+if (error.value) {
+  useToast().add({
+    title: 'Error',
+    description: error.value.message,
+    color: 'red',
+  })
+  return
+}
+```
+
+### 3. Use Computed for Response Data
+
+```typescript
+// ✅ Good - Extract data into computed
+const { data: response } = await useApi<User[]>('/users')
+const users = computed(() => response.value?.data || [])
+
+// Now use users in template
+<template>
+  <div v-for="user in users" :key="user.id">
+    {{ user.name }}
+  </div>
+</template>
+```
+
+### 4. Leverage Immediate: false for Forms
+
+```typescript
+// ✅ Good for submit handlers
+const { execute, pending, error } = await useApi('/users', {
+  method: 'POST',
+  body: form,
+  immediate: false,
+})
+
+const handleSubmit = async () => {
+  await execute()
+  // Handle response
+}
+```
+
+### 5. Use Watch for Reactive Queries
+
+```typescript
+// ✅ Good - Reactive filters
+const filters = reactive({
+  role: 'admin',
+  status: 'active',
+})
+
+const { data } = await useApi('/users', {
+  query: filters,
+  watch: [() => filters.role, () => filters.status],
+})
+```
+
+---
+
+## Migration Guide
+
+### From useFetch to useApi
+
+```typescript
+// Before
+const { data, pending, error, refresh } = await useFetch('/api/users', {
+  headers: useRequestHeaders(['cookie']),
+  query: { page: 1 },
+})
+
+// After
+const { data, pending, error, refresh } = await useApi('/users', {
+  query: { page: 1 },
+})
+// Simpler! Auth automatic.
+```
+
+### From $fetch to useApi
+
+```typescript
+// Before
+const loading = ref(false)
+const error = ref(null)
+const users = ref([])
+
+const fetchUsers = async () => {
+  loading.value = true
+  try {
+    users.value = await $fetch('/api/users')
+  } catch (err) {
+    error.value = err
+  } finally {
+    loading.value = false
+  }
+}
+
+onMounted(fetchUsers)
+
+// After
+const { data: users, pending, error } = await useApi('/users')
+// Much simpler! Reactive state automatic.
+```
+
+### From useAsyncData to useApi
+
+```typescript
+// Before
+const { data, pending, error } = await useAsyncData('users', () => $fetch('/api/users'))
+
+// After
+const { data, pending, error } = await useApi('/users')
+// Cleaner! No manual key needed.
+```
+
+---
+
+## Common Patterns Cheatsheet
+
+| Use Case       | Code                                                         |
+| -------------- | ------------------------------------------------------------ |
+| Simple GET     | `await useApi<T>('/endpoint')`                               |
+| GET with query | `await useApi('/endpoint', { query: { key: 'value' } })`     |
+| POST           | `await useApi('/endpoint', { method: 'POST', body: data })`  |
+| PUT/PATCH      | `await useApi('/endpoint', { method: 'PATCH', body: data })` |
+| DELETE         | `await useApi('/endpoint', { method: 'DELETE' })`            |
+| Manual trigger | `await useApi('/endpoint', { immediate: false })`            |
+| Reactive query | `await useApi('/endpoint', { query, watch: [query] })`       |
+| Error handling | `if (error.value) { console.log(error.value.message) }`      |
+| Refresh        | `await refresh()`                                            |
+| Re-execute     | `await execute()`                                            |
+
+---
+
+## Summary
+
+**When to use useApi:**
+
+- ✅ All internal API calls (recommended default)
+- ✅ Protected routes requiring authentication
+- ✅ Consistent error handling needed
+- ✅ Want automatic SSR/CSR optimization
+
+**When to use useFetch:**
+
+- ⚠️ External third-party APIs
+- ⚠️ Custom caching requirements
+- ⚠️ Special configurations not supported by useApi
+
+**When to use $fetch:**
+
+- ⚠️ Server-side only code (server/api/\*)
+- ⚠️ One-off requests without reactive state
+- ⚠️ Background jobs or scheduled tasks
+
+**Default choice: useApi for 99% of cases in this project.**
+
+---
+
+For more examples, see:
+
+- [EXAMPLES.md](./EXAMPLES.md) - Section 3: API Integration
+- [CHEATSHEET.md](./CHEATSHEET.md) - Data Fetching section
+- [frontend-developer.md](./frontend-developer.md) - Data Fetching Patterns
+
+**Happy coding with useApi! 🚀**