@famgia/omnify-ai-guides 2.0.15

package/dist/knowledge/react/laravel-integration.md.stub

@@ -0,0 +1,181 @@
+# Laravel Integration
+
+> **Related:** [README](./README.md) | [Service Pattern](./service-pattern.md)
+
+## Sanctum Authentication Flow
+
+```typescript
+// Step 1: Get CSRF cookie (required before POST requests)
+await api.get("/sanctum/csrf-cookie");
+
+// Step 2: Login
+await api.post("/login", { email, password });
+// Cookie is now set automatically
+
+// Step 3: Access protected routes
+await api.get("/api/user"); // Works! Cookie sent automatically
+```
+
+---
+
+## Error Handling Map
+
+| HTTP Status | Laravel Meaning     | Frontend Action           |
+| ----------- | ------------------- | ------------------------- |
+| 200         | Success             | Process response          |
+| 201         | Created             | Process response          |
+| 204         | No Content          | Success (no body)         |
+| 401         | Unauthenticated     | Redirect to `/login`      |
+| 403         | Forbidden           | Show error message        |
+| 404         | Not Found           | Show error message        |
+| 419         | CSRF Token Mismatch | Refresh page              |
+| 422         | Validation Error    | Display in form fields    |
+| 429         | Too Many Requests   | Show rate limit message   |
+| 500+        | Server Error        | Show server error message |
+
+---
+
+## API Response Types
+
+### Laravel Pagination Response
+
+```typescript
+interface PaginatedResponse<T> {
+  data: T[];
+  links: {
+    first: string | null;
+    last: string | null;
+    prev: string | null;
+    next: string | null;
+  };
+  meta: {
+    current_page: number;
+    from: number | null;
+    last_page: number;
+    per_page: number;
+    to: number | null;
+    total: number;
+  };
+}
+```
+
+### Laravel API Resource Response (single item)
+
+```typescript
+interface ResourceResponse<T> {
+  data: T;
+}
+```
+
+### Laravel Validation Error Response (422)
+
+```typescript
+interface ValidationErrorResponse {
+  message: string;
+  errors: Record<string, string[]>;
+}
+```
+
+---
+
+## Handling Laravel Responses
+
+### In Service Layer
+
+```typescript
+const userService = {
+  // Paginated list
+  list: async (params?: UserListParams): Promise<PaginatedResponse<User>> => {
+    const { data } = await api.get("/api/users", { params });
+    return data;  // Already typed as PaginatedResponse
+  },
+
+  // Single resource (handle { data: ... } wrapper)
+  get: async (id: number): Promise<User> => {
+    const { data } = await api.get(`/api/users/${id}`);
+    return data.data ?? data;  // Handle both wrapped and unwrapped
+  },
+};
+```
+
+### In Components (Form Validation)
+
+```typescript
+import { getFormErrors } from "@/lib/api";
+
+const mutation = useMutation({
+  mutationFn: userService.create,
+  onError: (error) => {
+    // Transform Laravel 422 errors to Ant Design format
+    form.setFields(getFormErrors(error));
+  },
+});
+```
+
+---
+
+## Axios Instance Configuration
+
+The `lib/api.ts` is pre-configured for Laravel Sanctum:
+
+```typescript
+const api = axios.create({
+  baseURL: process.env.NEXT_PUBLIC_API_URL,
+  timeout: 30000,
+  headers: {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  },
+  withCredentials: true,      // Required for Sanctum cookies
+  withXSRFToken: true,        // Auto send XSRF-TOKEN cookie as header
+  xsrfCookieName: "XSRF-TOKEN",
+  xsrfHeaderName: "X-XSRF-TOKEN",
+});
+```
+
+---
+
+## Common Patterns
+
+### Login Flow
+
+```typescript
+import { csrf } from "@/lib/api";
+
+const login = async (email: string, password: string) => {
+  // 1. Get CSRF cookie first
+  await csrf();
+  
+  // 2. Login
+  await api.post("/login", { email, password });
+  
+  // 3. Get user data
+  const { data } = await api.get("/api/user");
+  return data;
+};
+```
+
+### Protected API Call
+
+```typescript
+// No special handling needed - cookies are sent automatically
+const users = await userService.list();
+```
+
+### Handling 401 (Unauthenticated)
+
+The interceptor in `lib/api.ts` automatically redirects to `/login` on 401:
+
+```typescript
+api.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response?.status === 401) {
+      if (!window.location.pathname.includes("/login")) {
+        window.location.href = "/login";
+      }
+    }
+    return Promise.reject(error);
+  }
+);
+```

package/dist/knowledge/react/service-pattern.md.stub

@@ -0,0 +1,180 @@
+# Service Layer Pattern
+
+> **Related:** [README](./README.md) | [TanStack Query](./tanstack-query.md) | [Laravel Integration](./laravel-integration.md)
+
+## Types Rule
+
+```typescript
+// ✅ DO: Import Model + Create/Update types from Omnify
+import type { User, UserCreate, UserUpdate } from "@omnify/schemas";
+
+// ✅ DO: Only define query params locally (not generated by Omnify)
+export interface UserListParams {
+  search?: string;
+  page?: number;
+}
+
+// ❌ DON'T: Define types that Omnify already generates
+export interface UserCreateInput { ... }  // WRONG - use UserCreate from Omnify
+export interface User { ... }              // WRONG - use User from Omnify
+```
+
+---
+
+## Service Template
+
+```typescript
+/**
+ * Users Service
+ *
+ * CRUD operations for User resource.
+ * Maps to Laravel UserController.
+ */
+
+import api, { PaginatedResponse } from "@/lib/api";
+import type { User, UserCreate, UserUpdate } from "@omnify/schemas";
+
+// =============================================================================
+// Types - Only query params (Create/Update come from Omnify)
+// =============================================================================
+
+/** Query params for listing users */
+export interface UserListParams {
+  search?: string;
+  page?: number;
+  per_page?: number;
+  sort_by?: keyof User;
+  sort_order?: "asc" | "desc";
+}
+
+// =============================================================================
+// Service
+// =============================================================================
+
+const BASE_URL = "/api/users";
+
+export const userService = {
+  /**
+   * Get paginated list of users
+   * GET /api/users
+   */
+  list: async (params?: UserListParams): Promise<PaginatedResponse<User>> => {
+    const { data } = await api.get(BASE_URL, { params });
+    return data;
+  },
+
+  /**
+   * Get single user by ID
+   * GET /api/users/:id
+   */
+  get: async (id: number): Promise<User> => {
+    const { data } = await api.get(`${BASE_URL}/${id}`);
+    return data.data ?? data;
+  },
+
+  /**
+   * Create new user
+   * POST /api/users
+   */
+  create: async (input: UserCreate): Promise<User> => {
+    const { data } = await api.post(BASE_URL, input);
+    return data.data ?? data;
+  },
+
+  /**
+   * Update existing user
+   * PUT /api/users/:id
+   */
+  update: async (id: number, input: UserUpdate): Promise<User> => {
+    const { data } = await api.put(`${BASE_URL}/${id}`, input);
+    return data.data ?? data;
+  },
+
+  /**
+   * Delete user
+   * DELETE /api/users/:id
+   */
+  delete: async (id: number): Promise<void> => {
+    await api.delete(`${BASE_URL}/${id}`);
+  },
+};
+```
+
+---
+
+## Service Rules
+
+```typescript
+// ✅ DO: Import all types from Omnify
+import type { User, UserCreate, UserUpdate } from "@omnify/schemas";
+
+// ❌ DON'T: Define types that Omnify generates
+export interface UserCreate { ... }  // WRONG!
+export interface User { ... }        // WRONG!
+
+// ✅ DO: Only define query params locally
+export interface UserListParams { ... }  // OK - not in Omnify
+
+// ✅ DO: Keep services pure (no React hooks)
+export const userService = {
+  get: (id) => api.get(`/api/users/${id}`).then(r => r.data.data ?? r.data),
+};
+
+// ❌ DON'T: Use React hooks in services
+export const userService = {
+  get: (id) => {
+    const [data, setData] = useState(); // WRONG!
+  },
+};
+
+// ✅ DO: Handle Laravel's { data: ... } wrapper
+get: (id) => api.get(`/api/users/${id}`).then(r => r.data.data ?? r.data),
+
+// ❌ DON'T: Return raw axios response
+get: (id) => api.get(`/api/users/${id}`), // Returns AxiosResponse, not data
+```
+
+---
+
+## Using Validation Rules
+
+```typescript
+import { Form, Input } from "antd";
+import { useLocale } from "next-intl";
+import { userSchemas, getUserFieldLabel } from "@omnify/schemas/User";
+import { zodRule } from "@/lib/form-validation";
+
+function UserForm() {
+  const locale = useLocale();
+  const label = (key: string) => getUserFieldLabel(key, locale);
+
+  return (
+    <Form>
+      {/* Name */}
+      <Form.Item 
+        name="name" 
+        label={label("name")}
+        rules={[zodRule(userSchemas.name, label("name"))]}
+      >
+        <Input />
+      </Form.Item>
+    </Form>
+  );
+}
+```
+
+---
+
+## Types Summary
+
+| Type     | Source                       | Example                                    |
+| -------- | ---------------------------- | ------------------------------------------ |
+| Model    | `@omnify/schemas` (Omnify)     | `User`                                     |
+| Create   | `@omnify/schemas` (Omnify)     | `UserCreate`                               |
+| Update   | `@omnify/schemas` (Omnify)     | `UserUpdate`                               |
+| Schemas  | `@omnify/schemas` (Omnify)     | `userSchemas.email`                        |
+| Params   | Service file (manual)        | `UserListParams`                           |
+| Response | `@/lib/api.ts`               | `PaginatedResponse<T>`                     |
+| Rules    | `@/lib/form-validation`      | `zodRule(schema, label)`                   |
+
+See [Types Guide](./types-guide.md) for complete details.

package/dist/knowledge/react/tanstack-query.md.stub

@@ -0,0 +1,339 @@
+# TanStack Query Guide
+
+> **Related:** [README](./README.md) | [Service Pattern](./service-pattern.md)
+
+## Query Keys Pattern
+
+### Structure
+
+```typescript
+// lib/queryKeys.ts
+
+import type { UserListParams } from "@/services/users";  // Import from service
+import type { PostListParams } from "@/services/posts";
+
+export const queryKeys = {
+  // Simple key
+  user: ["user"] as const,
+
+  // Resource with nested keys - USE TYPED PARAMS
+  users: {
+    all: ["users"] as const,
+    lists: () => [...queryKeys.users.all, "list"] as const,
+    list: (params?: UserListParams) => [...queryKeys.users.lists(), params] as const,
+    details: () => [...queryKeys.users.all, "detail"] as const,
+    detail: (id: number) => [...queryKeys.users.details(), id] as const,
+  },
+
+  posts: {
+    all: ["posts"] as const,
+    lists: () => [...queryKeys.posts.all, "list"] as const,
+    list: (params?: PostListParams) => [...queryKeys.posts.lists(), params] as const,
+    details: () => [...queryKeys.posts.all, "detail"] as const,
+    detail: (id: number) => [...queryKeys.posts.details(), id] as const,
+    byUser: (userId: number) => [...queryKeys.posts.all, "user", userId] as const,
+  },
+} as const;
+```
+
+### ⚠️ Type Rule
+
+```typescript
+// ✅ DO: Import and use specific types from service
+import type { UserListParams } from "@/services/users";
+list: (params?: UserListParams) => [...]
+
+// ❌ DON'T: Use generic Record type
+list: (params?: Record<string, unknown>) => [...]  // Hard to read, no autocomplete
+```
+
+### Rules
+
+```typescript
+// ✅ DO: Use query key factory
+useQuery({
+  queryKey: queryKeys.users.detail(id),
+  queryFn: () => userService.get(id),
+});
+
+// ❌ DON'T: Hardcode query keys
+useQuery({
+  queryKey: ["users", "detail", id], // Hard to maintain
+  queryFn: () => userService.get(id),
+});
+
+// ✅ DO: Include all dependencies in key
+useQuery({
+  queryKey: queryKeys.users.list({ page, search }), // Refetches when params change
+  queryFn: () => userService.list({ page, search }),
+});
+
+// ❌ DON'T: Omit dependencies
+useQuery({
+  queryKey: queryKeys.users.list(), // Won't refetch when params change
+  queryFn: () => userService.list({ page, search }),
+});
+```
+
+---
+
+## Mutation Pattern
+
+### Standard CRUD Mutations
+
+```typescript
+"use client";
+
+import { Form, Button } from "antd";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { message } from "antd";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { queryKeys } from "@/lib/queryKeys";
+import { getFormErrors } from "@/lib/api";
+import { userService, UserUpdateInput } from "@/services/users";
+
+export default function CreateUserPage() {
+  const t = useTranslations();  // No namespace = access all
+  const router = useRouter();
+  const queryClient = useQueryClient();
+  const [form] = Form.useForm();
+
+  // CREATE mutation
+  const createMutation = useMutation({
+    mutationFn: userService.create,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+      message.success(t("messages.created"));
+      router.push("/users");
+    },
+    onError: (error) => {
+      form.setFields(getFormErrors(error));
+    },
+  });
+
+  // UPDATE mutation
+  const updateMutation = useMutation({
+    mutationFn: ({ id, data }: { id: number; data: UserUpdateInput }) =>
+      userService.update(id, data),
+    onSuccess: (_, { id }) => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+      queryClient.invalidateQueries({ queryKey: queryKeys.users.detail(id) });
+      message.success(t("messages.updated"));
+      router.push(`/users/${id}`);
+    },
+    onError: (error) => {
+      form.setFields(getFormErrors(error));
+    },
+  });
+
+  // DELETE mutation
+  const deleteMutation = useMutation({
+    mutationFn: userService.delete,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+      message.success(t("messages.deleted"));
+      router.push("/users");
+    },
+  });
+
+  return (
+    <Form form={form} onFinish={(values) => createMutation.mutate(values)}>
+      {/* ... form fields ... */}
+      <Button type="primary" htmlType="submit" loading={createMutation.isPending}>
+        {t("common.save")}
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Mutation Rules
+
+```typescript
+// ✅ DO: Always invalidate related queries after mutation
+onSuccess: () => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+}
+
+// ❌ DON'T: Forget to invalidate
+onSuccess: () => {
+  message.success("Saved!"); // Data won't refresh!
+}
+
+// ✅ DO: Handle form errors from Laravel
+onError: (error) => {
+  form.setFields(getFormErrors(error));
+}
+
+// ❌ DON'T: Ignore errors
+onError: (error) => {
+  console.log(error); // User sees nothing
+}
+
+// ✅ DO: Show loading state
+<Button loading={mutation.isPending}>Submit</Button>
+
+// ❌ DON'T: No loading feedback
+<Button>Submit</Button> // User can double-click
+```
+
+---
+
+## Advanced Tips
+
+### Keep Queries Simple
+
+```typescript
+// ✅ SIMPLE: queryFn just calls service
+useQuery({
+  queryKey: queryKeys.users.list(filters),
+  queryFn: () => userService.list(filters),
+});
+
+// ❌ OVER-ENGINEERED: Logic in queryFn
+useQuery({
+  queryKey: queryKeys.users.list(filters),
+  queryFn: async () => {
+    const data = await userService.list(filters);
+    return data.map(transform).filter(validate); // Move this to service!
+  },
+});
+```
+
+### Query Key = All Dependencies
+
+```typescript
+// ✅ CORRECT: Key includes all params → auto refetch when changed
+useQuery({
+  queryKey: queryKeys.users.list({ page, search, status }),
+  queryFn: () => userService.list({ page, search, status }),
+});
+
+// ❌ WRONG: Missing deps in key → stale data
+useQuery({
+  queryKey: queryKeys.users.list(),
+  queryFn: () => userService.list({ page, search }),  // Params not in key!
+});
+```
+
+### Conditional Queries with `enabled`
+
+```typescript
+// Fetch user first, then fetch user's posts
+const { data: user } = useQuery({
+  queryKey: queryKeys.user,
+  queryFn: authService.me,
+});
+
+const { data: posts } = useQuery({
+  queryKey: queryKeys.posts.byUser(user?.id!),
+  queryFn: () => postService.listByUser(user!.id),
+  enabled: !!user,  // ← Only runs when user exists
+});
+```
+
+### Invalidate Correctly
+
+```typescript
+// ✅ Invalidate by prefix (all user queries)
+queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+
+// ✅ Invalidate specific query
+queryClient.invalidateQueries({ queryKey: queryKeys.users.detail(id) });
+
+// ❌ DON'T invalidate everything
+queryClient.invalidateQueries();  // Too broad!
+
+// ❌ DON'T refetch manually
+await userService.create(data);
+refetch();  // Wrong! Use invalidateQueries
+```
+
+### Optimistic Updates (Use Sparingly)
+
+Only for instant feedback UX (like/unlike, toggle, drag-drop):
+
+```typescript
+const likeMutation = useMutation({
+  mutationFn: postService.like,
+  onMutate: async (postId) => {
+    await queryClient.cancelQueries({ queryKey: queryKeys.posts.detail(postId) });
+    const previous = queryClient.getQueryData(queryKeys.posts.detail(postId));
+    queryClient.setQueryData(queryKeys.posts.detail(postId), (old: Post) => ({
+      ...old,
+      liked: true,
+      likesCount: old.likesCount + 1,
+    }));
+    return { previous };
+  },
+  onError: (err, postId, context) => {
+    queryClient.setQueryData(queryKeys.posts.detail(postId), context?.previous);
+  },
+  onSettled: (data, error, postId) => {
+    queryClient.invalidateQueries({ queryKey: queryKeys.posts.detail(postId) });
+  },
+});
+```
+
+### Prefetching (For Better UX)
+
+```typescript
+<Link 
+  href={`/users/${user.id}`}
+  onMouseEnter={() => {
+    queryClient.prefetchQuery({
+      queryKey: queryKeys.users.detail(user.id),
+      queryFn: () => userService.get(user.id),
+    });
+  }}
+>
+  {user.name}
+</Link>
+```
+
+---
+
+## Common Mistakes
+
+```typescript
+// ❌ Mixing server state with local state
+const [users, setUsers] = useState([]);  // DELETE THIS
+const { data } = useQuery({...});        // USE THIS ONLY
+
+// ❌ Fetching in useEffect
+useEffect(() => {
+  fetchUsers().then(setUsers);  // WRONG
+}, []);
+// ✅ Use useQuery instead
+
+// ❌ Missing error handling in mutation
+const mutation = useMutation({
+  mutationFn: userService.create,
+  onSuccess: () => message.success("Created"),
+  // MISSING: onError for form validation!
+});
+
+// ✅ Always handle errors
+const mutation = useMutation({
+  mutationFn: userService.create,
+  onSuccess: () => message.success(t("created")),
+  onError: (error) => form.setFields(getFormErrors(error)),
+});
+```
+
+---
+
+## When NOT to Use TanStack Query
+
+```typescript
+// ❌ For client-only state (use useState or Zustand)
+const [isModalOpen, setIsModalOpen] = useState(false);
+const [selectedItems, setSelectedItems] = useState<number[]>([]);
+
+// ❌ For derived/computed values (use useMemo)
+const filteredUsers = useMemo(
+  () => users.filter(u => u.active),
+  [users]
+);
+```