@nexa-stack/framework 1.0.0

package/docs/START.md

@@ -0,0 +1,98 @@
+# Nexa — Start here
+
+Ship a full backend in hours: API, ORM, auth, queue, and admin.
+
+**Runtime:** Node.js ≥ 20  
+**Default language:** English (`APP_LOCALE=en`)
+
+## Four words
+
+| Word | Meaning |
+|------|---------|
+| `resource` | Table + API + CRUD |
+| Fields (`string`…) | Column types |
+| `.admin()` | Admin UI + auth + soft delete |
+| `nexa serve` | Run |
+
+## Full app (one file)
+
+```ts
+import { resource, string, text, boolean, select, money, belongsTo, belongsToMany } from "@nexa-stack/framework";
+
+resource("clients", {
+  name: string().required().label("Name"),
+  phone: string().label("Phone"),
+}, { label: "Clients" }).admin();
+
+resource("orders", {
+  client: belongsTo("clients").required().label("Client"),
+  total: money().required().label("Total"),
+  status: select(["new", "paid", "cancelled"]).label("Status"),
+  note: text().label("Note"),
+}, { label: "Orders" }).admin();
+```
+
+```bash
+nexa serve
+```
+
+→ http://localhost:3333/admin  
+→ `admin@nexa.dev` / `123456`
+
+No controllers · no hand-written routes · missing columns are added automatically when you change a resource.
+
+## Commands
+
+```bash
+nexa new my-app
+nexa make:resource products   # loads from resources/
+nexa serve
+nexa migrate:rollback         # roll back last file migration
+```
+
+## Field types
+
+`string` `text` `number` `boolean` `email` `money` `date` `datetime` `select([...])`  
+`belongsTo` `hasMany` `belongsToMany` `file` `image`
+
+## Extra power (optional)
+
+```ts
+import { db } from "@nexa-stack/framework";
+
+const rows = await db.from("orders")
+  .where("status", "paid")
+  .with("client")
+  .orderBy("id", "desc")
+  .get();
+
+await db.transaction(async (tx) => {
+  await tx.from("orders").insert({ ... });
+});
+```
+
+Thin frontend bridge: `createClient({ baseUrl, token })`.
+
+## Scale (when you grow)
+
+```bash
+nexa queue:work
+# LIST_CACHE_TTL=15
+# RATE_LIMIT_DRIVER=redis
+```
+
+`/health` and `/ready` for load balancers.
+
+## Arabic UI (optional)
+
+```env
+APP_LOCALE=en
+```
+
+Keep `lang/ar.json` + `lang/en.json`. Admin can switch languages.
+
+## Security
+
+`.admin()` requires admin auth. Soft delete is on by default.
+
+**Full reference:** [REFERENCE.md](./REFERENCE.md)

package/docs/advanced.md

@@ -0,0 +1,97 @@
+# Advanced Features
+
+## Soft deletes
+
+```ts
+resource("clients", {
+  name: string().required(),
+}).softDeletes().admin();
+```
+
+- `DELETE /api/clients/1` → soft (sets `deleted_at`)
+- `DELETE /api/clients/1?force=1` → hard delete
+- `POST /api/clients/1/restore` → restore
+- `GET /api/clients?trashed=only` → trash only
+- `GET /api/clients?trashed=with` → include deleted
+
+## Export
+
+```
+GET /api/clients/export?format=csv
+GET /api/clients/export?format=json
+```
+
+## SMS
+
+```ts
+import { sms } from "./packages/core/src/index.js";
+await sms("0501234567", "Verification code: 1234");
+```
+
+```env
+SMS_DRIVER=log          # default → storage/logs/sms.log
+# SMS_DRIVER=webhook
+# SMS_WEBHOOK=https://...
+```
+
+## Middleware
+
+```ts
+import { use, rateLimit, cors } from "./packages/core/src/index.js";
+
+use(cors());
+use(rateLimit(100, 60_000)); // 100 req / minute
+
+use(async (req, user, next) => {
+  console.log(req.method, req.url);
+  return next();
+});
+```
+
+Default on `start()`: CORS + rate limit (`RATE_LIMIT`, default 120/min).
+
+## Plugins
+
+```ts
+import { plugin } from "./packages/core/src/index.js";
+
+plugin({
+  name: "audit",
+  boot: () => console.log("audit ready"),
+  hooks: {
+    "resource.created": async ({ resource, data }) => {
+      console.log("created", resource, data);
+    },
+  },
+});
+```
+
+## Testing helpers
+
+```ts
+import { resource, string, createTestApp } from "./packages/core/src/index.js";
+
+resource("items", { name: string().required() });
+const app = await createTestApp();
+
+const res = await app.request("POST", "/api/items", {
+  body: JSON.stringify({ name: "X" }),
+});
+
+const asAdmin = app.actingAs({ id: 1, email: "a@b.com", role: "admin" });
+await asAdmin.request("GET", "/api/items");
+
+app.close();
+```
+
+## vs Laravel
+
+| Laravel | Nexa |
+|---------|------|
+| SoftDeletes trait | `.softDeletes()` |
+| Excel/Export | `/export?format=csv` |
+| Notification SMS | `sms()` |
+| Middleware | `use()` |
+| RateLimiter | `rateLimit()` |
+| Service Provider / Package | `plugin()` |
+| Feature tests | `createTestApp()` |

package/docs/authentication.md

@@ -0,0 +1,54 @@
+# Authentication
+
+## Login / Register
+
+```
+POST /api/auth/register  { email, password }
+POST /api/auth/login     { email, password }  → { user, token }
+```
+
+Use: `Authorization: Bearer {token}`
+
+Protect resources: `.auth()` or `.policy({...})`
+
+Default admin: `admin@nexa.dev` / `123456`
+
+## Password reset
+
+```
+POST /api/auth/forgot-password  { email }
+POST /api/auth/reset-password   { email, token, password }
+```
+
+Token is emailed (`MAIL_DRIVER=log` → `storage/logs/mail.log` in dev).
+
+```ts
+import { forgotPassword, resetPassword } from "@nexa-stack/framework";
+
+await forgotPassword("ali@corp.com");
+await resetPassword("ali@corp.com", token, "new-password");
+```
+
+## Email verification
+
+On register, a verification email is sent.
+
+```
+GET  /api/auth/verify-email?email=...&token=...
+POST /api/auth/verify-email  { email, token }
+POST /api/auth/resend-verification  { email }
+```
+
+```ts
+import { verifyEmail, resendVerification } from "@nexa-stack/framework";
+```
+
+`users.email_verified_at` is set when verified.
+
+## .env
+
+```env
+APP_URL=http://localhost:3333
+APP_SECRET=change-me
+MAIL_DRIVER=log
+```

package/docs/cli.md

@@ -0,0 +1,15 @@
+# CLI
+
+```bash
+npm run serve              # or: npx nexa serve
+npx nexa migrate           # run migrations
+npx nexa db:seed           # seed database
+npx nexa queue:work        # process queued jobs
+npx nexa schedule:work     # run scheduled tasks
+npx nexa make:resource clients
+npm test                   # run tests
+```
+
+## make:resource
+
+Creates `resources/clients.ts` — auto-loaded from `resources/` (no import needed).

package/docs/compare.md

@@ -0,0 +1,51 @@
+# Nexa vs Laravel
+
+Browser page: **[/compare](/compare)**
+
+## CLI
+
+| Task | Laravel | Nexa |
+|------|---------|------|
+| Serve | `php artisan serve` | `nexa serve` |
+| Migrate | `php artisan migrate` | `nexa migrate` |
+| Seed | `php artisan db:seed` | `nexa db:seed` |
+| Queue | `php artisan queue:work` | `nexa queue:work` |
+| Schedule | `php artisan schedule:work` | `nexa schedule:work` |
+| Make | `php artisan make:model X -mcr` | `nexa make:resource x` |
+| Test | `php artisan test` | `nexa test` |
+
+## Defining a resource
+
+**Laravel:** Migration + Model + Controller + Route  
+**Nexa:**
+
+```ts
+resource("posts", {
+  title: string().required(),
+  body: text(),
+}).admin().auth().softDeletes();
+```
+
+## Concepts
+
+| Laravel | Nexa |
+|---------|------|
+| Eloquent Model | `resource()` |
+| Migration files | auto from fields |
+| Controller | auto CRUD |
+| `Route::apiResource` | `/api/{name}` |
+| FormRequest | field builders |
+| SoftDeletes | `.softDeletes()` |
+| Policy | `.policy()` |
+| Filament/Nova | `.admin()` |
+
+## Services
+
+| Laravel | Nexa |
+|---------|------|
+| `Mail::` | `mail()` |
+| `Cache::` | `cache` |
+| `Log::` | `log` |
+| `dispatch()` | `dispatch()` |
+
+Open [/compare](/compare) for side-by-side tables and code.

package/docs/configuration.md

@@ -0,0 +1,65 @@
+# Configuration
+
+All config via `.env` (loaded automatically on start).
+
+## Core
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `PORT` | `3333` | HTTP port |
+| `APP_SECRET` | `change-me` | JWT signing secret |
+| `APP_URL` | `http://localhost:3333` | Used in reset/verify email links |
+| `APP_LOCALE` | `en` | Default UI language (`en` or `ar`) |
+
+## Database
+
+| Key | Example | Description |
+|-----|---------|-------------|
+| `DB_PATH` | `./app.db` | SQLite file (default) |
+| `DATABASE_URL` | `postgresql://user:pass@localhost:5432/nexa` | PostgreSQL |
+| `DATABASE_URL` | `mysql://user:pass@localhost:3306/nexa` | MySQL / MariaDB |
+
+If `DATABASE_URL` is set, it wins over `DB_PATH`.
+
+## Mail
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `MAIL_DRIVER` | `log` | `log` or `smtp` |
+| `MAIL_FROM` | `nexa@localhost` | From address |
+| `MAIL_HOST` | | SMTP host |
+| `MAIL_PORT` | `587` | SMTP port |
+| `MAIL_USER` | | SMTP user |
+| `MAIL_PASS` | | SMTP password |
+| `MAIL_SECURE` | `false` | TLS |
+
+`log` writes to `storage/logs/mail.log` (good for local/dev).
+
+## Cache / SMS / Limits
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `CACHE_DRIVER` | `memory` | `memory` · `file` · `redis` |
+| `REDIS_URL` | `redis://127.0.0.1:6379` | When cache is redis |
+| `SMS_DRIVER` | `log` | `log` or `webhook` |
+| `SMS_WEBHOOK` | | POST target for SMS |
+| `RATE_LIMIT` | `120` | Requests per minute per IP (0 = off) |
+| `LOG_LEVEL` | `debug` | `debug` · `info` · `warn` · `error` |
+
+## Example production `.env`
+
+```env
+APP_SECRET=long-random-string
+APP_URL=https://api.yourapp.com
+DATABASE_URL=postgresql://nexa:secret@db:5432/nexa
+MAIL_DRIVER=smtp
+MAIL_HOST=smtp.mailgun.org
+MAIL_PORT=587
+MAIL_USER=...
+MAIL_PASS=...
+MAIL_FROM=noreply@yourapp.com
+CACHE_DRIVER=redis
+REDIS_URL=redis://redis:6379
+RATE_LIMIT=120
+LOG_LEVEL=info
+```