routesync 1.0.26 → 1.0.27

package/README.md

@@ -2,7 +2,7 @@
 
 > Stop writing API clients by hand.
 
-RouteSync syncs your Laravel (or PHP) routes to a fully-typed frontend SDK — complete with TypeScript types, a camelCase mapper, and React/Vue Query hooks. One command. Zero boilerplate.
+RouteSync syncs your Laravel (or PHP) routes to a fully-typed frontend SDK — complete with TypeScript types, a camelCase mapper, React/Vue Query hooks, and Next.js Server Actions. One command. Zero boilerplate.
 
 ---
 
@@ -13,21 +13,26 @@ You've been there. The backend ships a new endpoint. You update the route, write
 RouteSync does all of that. You point it at `routes/api.php` and it generates the whole thing.
 
 ```bash
-npx routesync sync --input routes/api.php --output src/api --baseURL https://api.myapp.com/api
-```
+# Step 1 — in your Laravel folder
+npx routesync scan --input routes/api.php --models
 
+# Step 2 — in your frontend folder
+npx routesync generate --manifest routesync.manifest.json --output src/api --next-actions --zod
 ```
-  routesync sync
-
-  ✔ Scanning Laravel routes (24 routes)
-  ✔ Generating types
-  ✔ Generating SDK
-  ✔ Generating hooks
 
-  Sync complete! → src/api
+```
+✔ Found 35 routes, 19 models → routesync.manifest.json
+
+✔ SDK generated → src/api
+  api.ts      Typed API client
+  types.ts    TypeScript interfaces (from real DB columns)
+  hooks.ts    React Query hooks
+  actions.ts  Next.js Server Actions
+  schemas.ts  Zod validation schemas
+  index.ts    Barrel export
 ```
 
-That's it. Your frontend has a typed client, response types, and ready-to-use hooks — and you didn't write any of it.
+That's it. Your frontend has a typed client, real DB-derived types, Zod schemas, and ready-to-use hooks — and you didn't write any of it.
 
 ---
 
@@ -35,10 +40,10 @@ That's it. Your frontend has a typed client, response types, and ready-to-use ho
 
 | Package | What it does |
 |---|---|
-| `@routesync/sdk` | The core developer API. `defineApi`, `createService`, `resource`. |
+| `@routesync/sdk` | The core developer API. `defineApi`, `endpoint`, `resource`, `createService`. |
 | `@routesync/core` | HTTP client engine, auth, path resolution, error handling. |
-| `@routesync/cli` | Scans routes, generates types + SDK + hooks. |
-| `@routesync/react` | React Query hooks factory built on `createService`. |
+| `@routesync/cli` | Scans routes + models, generates types + SDK + hooks + actions. |
+| `@routesync/react` | `useApiQuery` / `useApiMutation` hooks built on TanStack Query. |
 | `@routesync/vue` | Vue Query composables, same idea. |
 
 ---
@@ -46,304 +51,338 @@ That's it. Your frontend has a typed client, response types, and ready-to-use ho
 ## Install
 
 ```bash
-# SDK only (manual route definitions)
-npm install @routesync/sdk
+# SDK + React hooks
+npm install routesync @tanstack/react-query
 
-# With React hooks
-npm install @routesync/react @tanstack/react-query
+# Vue composables
+npm install routesync @tanstack/vue-query
 
-# With Vue composables
-npm install @routesync/vue @tanstack/vue-query
-
-# CLI (route scanner + code generator)
-npm install -g @routesync/cli
+# With Zod validation
+npm install routesync zod
 ```
 
 ---
 
-## Usage
-
-### Option A — Define routes manually
+## Full Workflow (Laravel + Next.js)
 
-Good if you don't have a Laravel backend, or want full control.
+### 1. Scan routes & models
 
-```ts
-import { defineApi } from '@routesync/sdk'
-
-export const api = defineApi(
-  {
-    auth: {
-      login:  { method: 'POST', path: '/login' },
-      logout: { method: 'POST', path: '/logout', auth: true },
-    },
-    products: {
-      list:   { method: 'GET',  path: '/products' },
-      detail: { method: 'GET',  path: '/products/:id' },
-      create: { method: 'POST', path: '/products', auth: true },
-    },
-  },
-  { baseURL: 'https://api.myapp.com/api' }
-)
-```
-
-Then call it:
-
-```ts
-// GET /products?page=1&search=kaos
-await api.products.list({ query: { page: 1, search: 'kaos' } })
+Run this from your **Laravel project root**:
 
-// GET /products/42
-await api.products.detail({ params: { id: 42 } })
-
-// POST /products
-await api.products.create({ body: { name: 'Kaos Polos', price: 89000 } })
+```bash
+npx routesync scan --input routes/api.php --models
 ```
 
-Path params resolve automatically. `:id` → the value you pass. No string concatenation, no manual URL building.
-
----
+| Option | Default | Description |
+|---|---|---|
+| `--input` | `routes/api.php` | Path to your Laravel routes file |
+| `--output` | `routesync.manifest.json` | Where to save the manifest |
+| `--baseURL` | `http://localhost/api` | API base URL |
+| `--models` | off | Also scan `app/Models/` for real DB column types |
+
+> **`--models` requirement:** PHP must be available in your terminal and your database must be accessible (`.env` configured). The scanner runs a temporary PHP script via Laravel's bootstrap to read `Schema::getColumns()` from each Eloquent model.
+
+> **Important — manifest location:** The manifest is saved in whichever folder you run `scan` from. If you run it from your Laravel root, copy the manifest to your frontend folder before running `generate`:
+>
+> ```bash
+> # Windows PowerShell
+> copy ..\routesync.manifest.json .
+>
+> # macOS / Linux
+> cp ../backend/routesync.manifest.json .
+> ```
 
-### Option B — Auto-generate from Laravel
+### 2. Generate the SDK
 
-Point the CLI at your routes file and let it generate everything.
+Run this from your **frontend project root**:
 
 ```bash
-npx routesync sync \
-  --input ../laravel-backend/routes/api.php \
+npx routesync generate \
+  --manifest routesync.manifest.json \
   --output src/api \
-  --baseURL https://api.myapp.com/api
+  --next-actions \
+  --zod
 ```
 
-Generated output:
+| Option | Default | Description |
+|---|---|---|
+| `--manifest` | `routesync.manifest.json` | Path to manifest from step 1 |
+| `--output` | `src/api` | Output folder |
+| `--next-actions` | off | Generate `actions.ts` (Next.js Server Actions) |
+| `--zod` | off | Generate `schemas.ts` (Zod validation) |
+| `--no-hooks` | off | Skip generating `hooks.ts` |
+| `--msw` | off | Generate MSW mock handlers |
+
+> **Windows PowerShell note:** Do not use backslash `\` for line continuation — PowerShell treats it differently. Run the command on a single line:
+>
+> ```powershell
+> npx routesync generate --manifest routesync.manifest.json --output src/api --next-actions --zod
+> ```
+
+### Generated files
 
 ```
 src/api/
-├── api.ts      ← typed API client
-├── types.ts    ← TypeScript interfaces
-└── hooks.ts    ← React Query hooks
-```
-
-To keep it in sync during development:
-
-```bash
-npx routesync watch --input routes/api.php --output src/api
+├── api.ts        ← defineApi() with all endpoints + Contract types
+├── types.ts      ← TypeScript interfaces (real DB columns when --models used)
+├── hooks.ts      ← useApiQuery / useApiMutation per endpoint
+├── actions.ts    ← Next.js Server Actions (--next-actions)
+├── schemas.ts    ← Zod schemas from FormRequest rules (--zod)
+├── index.ts      ← Barrel re-export
+└── core/
+    └── models.ts ← Raw Eloquent model interfaces (when --models used)
 ```
 
----
+### 3. Initialize the client
 
-### Authentication
+Call `createClient` once at app startup (e.g. in your layout or provider):
 
 ```ts
-import { createClient } from '@routesync/sdk'
+// src/lib/api-client.ts
+import { createClient } from 'routesync'
 
-const { setToken, clearToken } = createClient({
-  baseURL: 'https://api.myapp.com/api'
+createClient({
+  baseURL: process.env.NEXT_PUBLIC_API_URL!, // e.g. http://localhost:8000/api
+  withCredentials: true,
 })
-
-// After login:
-setToken(response.data.token)
-
-// On logout:
-clearToken()
 ```
 
-Any route with `auth: true` in its definition automatically gets `Authorization: Bearer TOKEN` injected. You don't think about it again.
+### 4. Use in components
 
----
-
-### React Query Hooks
-
-```ts
-import { createService } from '@routesync/sdk'
-import { createHooks } from '@routesync/react'
-import { z } from 'zod'
-
-const productSchema = z.object({
-  id: z.number(),
-  product_name: z.string(),
-  price: z.number(),
-})
+```tsx
+import { useApiQuery, useApiMutation } from 'routesync/react'
+import { api } from '@/api/api'
 
-const productService = createService(client, '/products', {
-  entitySchema: productSchema,
-  listSchema: z.array(productSchema),
-})
+// GET — fetch data
+function ProdukList() {
+  const { data, isLoading } = useApiQuery(api.produk.get, {
+    query: { page: 1, search: 'kaos' }
+  })
 
-const { useList, useDetail, useCreate } = createHooks(productService, 'products')
-```
+  if (isLoading) return <p>Loading...</p>
+  return <ul>{data?.map(p => <li key={p.id}>{p.nama}</li>)}</ul>
+}
 
-In your component:
+// GET with path params
+function ProdukDetail({ id }: { id: string }) {
+  const { data } = useApiQuery(api.produk.getId, { params: { id } })
+  return <div>{data?.nama}</div>
+}
 
-```tsx
-function ProductList() {
-  const { data, isLoading } = useList({ page: 1 })
-  const mutation = useCreate()
+// POST / mutation
+function AddToCart({ produkItemId }: { produkItemId: string }) {
+  const mutation = useApiMutation(api.cart.postItems)
 
   return (
-    <>
-      {data?.map(p => <div key={p.id}>{p.productName}</div>)}
-      <button onClick={() => mutation.mutate({ productName: 'Kaos Baru' })}>
-        Add Product
-      </button>
-    </>
+    <button onClick={() => mutation.mutate({ body: { produk_item_id: produkItemId, qty: 1 } })}>
+      Tambah ke Keranjang
+    </button>
   )
 }
 ```
 
-Backend returns `product_name`. Your component sees `productName`. The mapper runs automatically in both directions — request payload goes snake_case before it hits the server, response comes back camelCase before it hits your component.
+### 5. Use Server Actions (Next.js)
 
----
+```ts
+// In a Server Component or form action
+import { produkGetAction, cartPostItemsAction } from '@/api/actions'
 
-### Vue Composables
+// GET — no params needed
+const result = await produkGetAction({ query: { page: 1 } })
+if (result.success) console.log(result.data)
 
-```ts
-import { createVueComposables } from '@routesync/vue'
+// POST — with body
+const result = await cartPostItemsAction({ body: { produk_item_id: '5', qty: 1 } })
 
-const { useList, useCreate } = createVueComposables(productService, 'products')
+// GET with path params — params are required
+const result = await produkGetIdAction({ params: { id: '42' } })
 ```
 
-Same API, Vue-native.
+---
+
+## Data Transformation
+
+RouteSync handles all data mapping automatically:
+
+| Direction | What happens | Where |
+|---|---|---|
+| Response (backend → frontend) | `snake_case` → `camelCase` keys | `HttpClient` interceptor |
+| Request (frontend → backend) | `camelCase` → `snake_case` keys | `HttpClient` interceptor |
+| Response unwrap | `{ data: T, message, meta }` → `T` | `HttpClient` `.get()` / `.post()` etc. |
+| Zod validation | Parse + validate response shape | Per-endpoint `responseSchema` |
+
+No extra config needed. `product_name` from Laravel becomes `productName` in your component automatically.
 
 ---
 
-### Resource groups
+## Manual Route Definitions
 
-When you have multiple endpoints on the same resource, `resource()` lets you set shared defaults (auth, headers) once:
+If you don't have a Laravel backend, define routes manually:
 
 ```ts
-import { defineApi, resource } from '@routesync/sdk'
+import { defineApi, endpoint, resource } from 'routesync'
+
+createClient({ baseURL: 'https://api.myapp.com/api' })
 
-const api = defineApi({
+export const api = defineApi({
+  // Basic endpoint
+  auth: {
+    login:  endpoint<{ token: string }>({ method: 'POST', path: '/login' }),
+    logout: endpoint({ method: 'POST', path: '/logout', auth: true }),
+  },
+
+  // With path params
+  produk: {
+    list:   endpoint<ProdukItem[]>({ method: 'GET', path: '/produk' }),
+    detail: endpoint<ProdukItem, { id: string }>({ method: 'GET', path: '/produk/:id' }),
+    create: endpoint<ProdukItem, unknown, CreateProdukBody>({
+      method: 'POST', path: '/produk', auth: true
+    }),
+  },
+
+  // resource() — shared auth/headers for a group
   cart: resource({
-    auth: true,  // applies to all endpoints below
+    auth: true,
     endpoints: {
-      list:     { method: 'GET',    path: '/cart/items' },
-      show:     { method: 'GET',    path: '/cart/items/:id' },
-      add:      { method: 'POST',   path: '/cart/items' },
-      update:   { method: 'PATCH',  path: '/cart/items/:id' },
-      remove:   { method: 'DELETE', path: '/cart/items/:id' },
-      checkout: { method: 'POST',   path: '/cart/checkout' },
+      get:    { method: 'GET',    path: '/cart' },
+      add:    { method: 'POST',   path: '/cart/items' },
+      update: { method: 'PATCH',  path: '/cart/items/:id' },
+      remove: { method: 'DELETE', path: '/cart/items/:id' },
     }
   })
-}, config)
+})
 ```
 
----
+`endpoint<TResponse, TParams, TBody>` — generic order:
+1. **TResponse** — shape returned by the backend
+2. **TParams** — path params like `{ id: string }`
+3. **TBody** — POST/PUT/PATCH body shape
 
-### Schema validation + custom mapping
+---
 
-You can attach Zod schemas to any endpoint for validation, and a mapper for custom transformations:
+## Authentication
 
 ```ts
-import { z } from 'zod'
-
-const api = defineApi({
-  products: {
-    list: {
-      method: 'GET',
-      path: '/products',
-      schema: z.array(productSchema),
-      mapper: (data) => data.map(normalizeProduct),
-    }
-  }
-}, config)
+import { createClient } from 'routesync'
+
+const client = createClient({ baseURL: 'https://api.myapp.com/api' })
+
+// After login — set token
+client.setToken(response.token)
+
+// On logout — clear token
+client.removeToken()
 ```
 
-> **Note on Laravel Auto-generation:** When using `routesync sync` or `routesync scan` with the `--zod` flag, RouteSync uses PHP Reflection to automatically generate Zod schemas based on your backend validation rules. 
-> 
-> **Important:** To ensure your schemas are detected automatically, you **must use Laravel `FormRequest` classes**. Inline `$request->validate([...])` calls inside Controller methods cannot be reliably extracted.
-> 
-> ```php
-> // ✅ DO THIS: RouteSync will generate Zod schemas automatically
-> public function store(StoreProductRequest $request)
-> 
-> // ❌ AVOID THIS: Validation rules will be ignored
-> public function store(Request $request) {
->     $request->validate([...]);
-> }
-> ```
+Any endpoint with `auth: true` automatically gets `Authorization: Bearer TOKEN` injected. For Next.js Server Actions, the generated `actions.ts` reads the token from cookies automatically via `getAuthHeaders()`.
 
 ---
 
-### Auto-generate TanStack hooks from defineApi
+## React Query Hooks
 
-If you're using `defineApi` (instead of `createService`), you can generate hooks for the whole API at once:
+### Auto-generated hooks (from CLI)
 
 ```ts
-import { defineApi } from '@routesync/sdk'
-import { generateHooks } from '@routesync/sdk'
+import { useApiQuery, useApiMutation } from 'routesync/react'
+import { api } from '@/api/api'
 
-const api = defineApi({ products: { list: ..., create: ... } }, config)
-const { useProductsList, useProductsCreate } = generateHooks(api)
+// GET
+const { data, isLoading } = useApiQuery(api.orders.get)
+
+// GET with params + query
+const { data } = useApiQuery(api.orders.getId, { params: { id: '1' } })
+
+// Mutation
+const mutation = useApiMutation(api.cart.postItems)
+mutation.mutate({ body: { produk_item_id: '5', qty: 1 } })
 ```
 
-Hook names are derived from group + action: `products.list` → `useProductsList`. GET/DELETE become `useQuery`, everything else becomes `useMutation`. Mutations auto-invalidate their group's queries on success.
+### Generate hooks for entire api at once
 
----
+```ts
+import { generateHooks } from 'routesync'
 
-### Multiple backends
+const hooks = generateHooks(api)
+const { useOrdersGet, useCartPostItems } = hooks
+// GET/DELETE → useQuery, everything else → useMutation
+```
 
-RouteSync isn't Laravel-only. Anything with a REST API works:
+### createHooks — per group
 
 ```ts
-const laravel = defineApi(routes, { baseURL: 'https://laravel.myapp.com/api' })
-const express = defineApi(routes, { baseURL: 'https://express.myapp.com/api' })
-const php     = defineApi(routes, { baseURL: 'https://php.myapp.com/api' })
+import { createHooks } from 'routesync/react'
+
+const cartHooks = createHooks(api.cart)
+const { usePostItems, usePatchItemsProdukItemId } = cartHooks
 ```
 
-The CLI also supports OpenAPI and native PHP alongside Laravel.
+---
+
+## Zod Schema Validation
+
+When using `--zod` with `routesync generate`, `schemas.ts` is generated from your Laravel `FormRequest` rules.
+
+> **Requirement:** You must use Laravel `FormRequest` classes for rules to be detected:
+>
+> ```php
+> // ✅ RouteSync will auto-generate Zod schema
+> public function store(StoreProductRequest $request) { ... }
+>
+> // ❌ Rules will not be detected
+> public function store(Request $request) {
+>     $request->validate([...]);
+> }
+> ```
 
 ---
 
-## CLI reference
+## CLI Reference
 
 ```bash
-# Scan routes → route manifest JSON
+# Scan Laravel routes only
 npx routesync scan --input routes/api.php
 
+# Scan routes + Eloquent models (recommended)
+npx routesync scan --input routes/api.php --models
+
 # Generate SDK from manifest
-npx routesync generate --manifest routesync.json --output src/api
+npx routesync generate --manifest routesync.manifest.json --output src/api
 
-# Scan + generate in one step
-npx routesync sync --input routes/api.php --output src/api --baseURL http://localhost/api
+# Generate everything
+npx routesync generate --manifest routesync.manifest.json --output src/api --next-actions --zod
 
-# Watch mode — auto-syncs on file change
+# Watch mode — auto re-generates on route file change
 npx routesync watch --input routes/api.php --output src/api
 ```
 
 ---
 
-## How it works
+## How It Works
 
 ```
-Laravel routes/api.php
-        ↓
-   routesync sync
-        ↓
-  Route manifest (JSON)
-        ↓  
-  SDK + types + hooks
-        ↓
-  React / Vue / Next.js / anywhere
+routes/api.php + app/Models/
+         ↓  routesync scan --models
+   routesync.manifest.json
+         ↓  routesync generate
+   src/api/
+    ├── api.ts       ← defineApi + endpoints
+    ├── types.ts     ← interfaces from DB columns
+    ├── hooks.ts     ← TanStack Query hooks
+    ├── actions.ts   ← Next.js Server Actions
+    └── schemas.ts   ← Zod schemas
+         ↓
+   React / Vue / Next.js
 ```
 
-The CLI parses your route file, builds a language-agnostic manifest, then feeds it to the generators. Each generator is independent — you can swap them out or write your own on top of the manifest format.
-
----
-
-## Roadmap
-
-- [ ] OpenAPI export from the manifest
-- [ ] SWR adapter alongside React Query
-- [ ] Solid.js composables
-- [ ] First-class Next.js Server Actions integration
-- [ ] VSCode extension — IntelliSense on `api.` without importing
+The CLI parses your route file via PHP reflection (using Laravel's own bootstrap), builds a language-agnostic manifest, then feeds it to independent generators. Each generator can be used standalone.
 
 ---
 
 ## Requirements
 
-- Node.js >= 18
+- Node.js >= 20
+- PHP available in PATH (for `scan --models`)
+- Laravel project with database accessible (for `scan --models`)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "routesync",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "description": "Laravel routes to typed frontend SDKs.",
   "main": "./dist/sdk.js",
   "module": "./dist/sdk.mjs",