flet-box 1.0.3 → 1.0.5

package/docs/server/api.md

@@ -0,0 +1,225 @@
+# API and routes
+
+## `Api()`
+
+`Api()` turns a readable route object into the internal route map used by the server.
+
+```javascript
+import { Api } from "flet-box-server";
+
+const routes = Api({
+  "/products": {
+    GET: {
+      handler: ({ query }) => ({
+        items: [],
+        search: query.search || null,
+      }),
+      tag: "products",
+      description: "List products",
+    },
+  },
+});
+```
+
+Supported methods are `GET`, `POST`, `PUT`, `DELETE`, and `PATCH`.
+
+## Handler styles
+
+A short handler can be a function:
+
+```javascript
+"/health": {
+  GET: () => ({ ok: true }),
+}
+```
+
+A detailed handler can include middleware, metadata, schemas, and examples:
+
+```javascript
+"/tasks": {
+  POST: {
+    handler: ({ title, completed }) => ({
+      id: 1,
+      title,
+      completed,
+    }),
+    middleware: [],
+    tag: "tasks",
+    description: "Create a task",
+    example: {
+      title: "Read the docs",
+      completed: false,
+    },
+    responseExample: {
+      id: 1,
+      title: "Read the docs",
+      completed: false,
+    },
+  },
+}
+```
+
+## URL parameters
+
+Use `:name` in a route path:
+
+```javascript
+"/users/:id": {
+  GET: ({ id }) => ({
+    userId: id,
+  }),
+}
+```
+
+The server matches `/users/42` and provides `id: "42"` to the handler.
+
+## Query parameters
+
+Query values are available through `query` or `req.query`:
+
+```javascript
+"/search": {
+  GET: ({ query }) => ({
+    term: query.term || "",
+    page: Number(query.page || 1),
+  }),
+}
+```
+
+Request example:
+
+```bash
+curl "http://localhost:3000/search?term=widgets&page=2"
+```
+
+## Request body
+
+For JSON requests, body fields are spread into the handler context:
+
+```javascript
+"/profile": {
+  PUT: {
+    handler: ({ name, email }) => ({ name, email }),
+    example: {
+      name: "Ada",
+      email: "ada@example.com",
+    },
+  },
+}
+```
+
+You can also access the original body through `req.body`.
+
+## Automatic request schemas
+
+When a method has an `example`, the server calls `inferSchema()` and stores the generated schema in the route documentation.
+
+```javascript
+example: {
+  name: "Ada",
+  age: 30,
+  active: true,
+  tags: ["developer"],
+}
+```
+
+Use real JavaScript values in examples. For example, `age: 30`, not `age: thirty`.
+
+The inferred schema detects strings, numbers, booleans, arrays, objects, email-like values, and URL-like values.
+
+## Manual schemas
+
+Use `schemas` when the inferred schema is not enough:
+
+```javascript
+"/users": {
+  POST: {
+    handler: ({ body }) => body,
+    schemas: {
+      CreateUser: {
+        type: "object",
+        properties: {
+          name: { type: "string", minLength: 2 },
+          email: { type: "email" },
+        },
+        required: ["name", "email"],
+      },
+    },
+  },
+}
+```
+
+For active validation, use `validate: true` in the server options or add validation middleware explicitly.
+
+## Response examples
+
+`responseExample` creates response documentation and a success response entry:
+
+```javascript
+responseExample: {
+  id: 1,
+  name: "Ada",
+}
+```
+
+## Middleware
+
+Middleware uses the Express-style `(req, res, next)` shape:
+
+```javascript
+const logRequest = (req, res, next) => {
+  console.log(req.method, req.url);
+  next();
+};
+
+const routes = Api({
+  "/health": {
+    GET: {
+      handler: () => ({ ok: true }),
+      middleware: [logRequest],
+    },
+  },
+});
+```
+
+## Generated documentation
+
+Enable docs when starting the server:
+
+```javascript
+runServer(routes, { docs: true });
+```
+
+The server exposes:
+
+```text
+GET /docs
+```
+
+The response groups endpoints by tag and includes methods, descriptions, schemas, responses, and generated curl, Python, and JavaScript examples.
+
+## HTTP responses
+
+Returning an object sends a JSON response with status `200`:
+
+```javascript
+"/status": {
+  GET: () => ({ status: "ok" }),
+}
+```
+
+For errors inside middleware, use:
+
+```javascript
+return res.error("Unauthorized", 401);
+```
+
+## Route checklist
+
+- Use a clear path.
+- Use the correct HTTP method.
+- Add `description` and `tag`.
+- Add `example` for body-based methods.
+- Add `responseExample` for useful response documentation.
+- Add authentication and validation where needed.
+- Do not expose secrets in examples or responses.

package/docs/server/data-services.md

@@ -0,0 +1,300 @@
+# Database and services
+
+## Where should your data live?
+
+A browser cannot run every database engine. The Node `better-sqlite3` library used by the server tools is a **native module** — it only runs on the server. Before choosing storage, decide where the data lives.
+
+### Option 1 — Browser only (no API)
+
+Data stays on the visitor's device. No server and no network calls.
+
+- **localStorage** — ships with the framework as `src/services/Storage.js` (`saveData`, `getData`, `updateData`, `deleteData`, ...). Synchronous, ~5 MB per origin, string values; the helpers serialize objects for you.
+- **IndexedDB** — asynchronous and much larger (gigabytes). Good for big records or offline files. Not bundled; call it directly or wrap it in a small helper.
+- **SQLite in the browser** — sql.js or sqlite-wasm run real SQL as WebAssembly. Not bundled.
+
+Choose this for drafts, per-device settings, offline caches, or single-user prototypes.
+
+### Option 2 — SQLite API server
+
+Data lives on your server and the UI talks to it over HTTP through the [API server section](#api-server-for-sqlite) below:
+
+```text
+UI widget (httpGet / httpPost / httpPut / httpDelete)
+        ↓ HTTPS + JSON
+Server routes (Api + runServer)
+        ↓
+SQLite (better-sqlite3 wrapper)
+```
+
+Choose this when data is shared between users or devices, must survive a browser reset, or is read by other systems.
+
+### Option 3 — Hybrid
+
+Use browser storage for offline cache and preferences, and sync with the API when the app is online.
+
+## SQLite database
+
+The current `Database` helper supports SQLite through the `SQLite` wrapper.
+
+> **Import rule:** the package root exports the core only. Every tool is a deep import (`flet-box-server/tools/<name>.js`) so that loading one never pulls in puppeteer, twilio, xlsx or the optional Google Cloud packages.
+
+```javascript
+import { Database } from "flet-box-server/tools/Database.js";
+
+const db = Database({
+  type: "sqlite",
+  path: "data/app.db",
+  tables: {
+    users: {
+      id: "INTEGER PRIMARY KEY AUTOINCREMENT",
+      name: "TEXT",
+      email: "TEXT",
+    },
+  },
+});
+```
+
+Use the generated table API:
+
+```javascript
+const result = db.users.insert({
+  name: "Ada",
+  email: "ada@example.com",
+});
+
+const users = db.users.readAll();
+const ada = db.users.readWhere(["email", "ada@example.com"], true);
+db.users.update({ name: "Ada Lovelace" }, ["email", "ada@example.com"]);
+db.users.delete(["email", "ada@example.com"]);
+```
+
+The lower-level SQLite class also provides table creation, updates, deletes, structure inspection, and reads.
+
+## API server for SQLite
+
+Wire the SQLite wrapper into the route server so the UI can read and write data safely over HTTP. Every wrapper method returns `[status, messageOrData]` — `true` when the operation succeeded.
+
+```javascript
+// server/index.js
+import { Api, runServer } from "flet-box-server/core/index.js";
+import { SQLite } from "flet-box-server/tools/betterSqlite.js";
+
+const db = new SQLite("data/app.db");
+db.createTable("users", {
+  id: "INTEGER PRIMARY KEY AUTOINCREMENT",
+  name: "TEXT",
+  email: "TEXT",
+});
+
+const routes = Api({
+  "/api/users": {
+    GET: () => {
+      const [ok, rows] = db.readAll("users");
+      return { ok, items: ok ? rows : [] };
+    },
+    POST: ({ body }) => {
+      const [ok, msg] = db.insert("users", {
+        name: body.name,
+        email: body.email,
+      });
+      return ok ? { ok } : { ok, error: msg };
+    },
+  },
+  "/api/users/:id": {
+    PUT: ({ id, body }) => {
+      const [ok, msg] = db.update("users", { email: body.email }, ["id", id]);
+      return ok ? { ok } : { ok, error: msg };
+    },
+    DELETE: ({ id }) => {
+      const [ok, msg] = db.delete("users", ["id", id]);
+      return ok ? { ok } : { ok, error: msg };
+    },
+  },
+});
+
+runServer(routes, { port: 3000, docs: true });
+```
+
+Consume the API from the UI with the framework HTTP client:
+
+```javascript
+// app.js (FletBox UI)
+import { httpGet, httpPost, httpPut, httpDelete } from "flet-box";
+
+const list = await httpGet("http://localhost:3000/api/users");
+const created = await httpPost("http://localhost:3000/api/users", {
+  body: { name: "Ada", email: "ada@example.com" },
+});
+const updated = await httpPut("http://localhost:3000/api/users/1", {
+  body: { email: "ada@lovelace.dev" },
+});
+const removed = await httpDelete("http://localhost:3000/api/users/1");
+```
+
+Start the server, then open the auto-generated docs at `http://localhost:3000/docs` to browse and test the endpoints.
+
+## Redis cache
+
+Configure Redis with `REDIS_URL`:
+
+```bash
+REDIS_URL=redis://localhost:6379
+```
+
+Use the cache helpers:
+
+```javascript
+import { connectRedis, cacheSet, cacheGet, cacheDel } from "flet-box-server/tools/cache.js";
+
+connectRedis();
+await cacheSet("user:1", { name: "Ada" }, 3600);
+const user = await cacheGet("user:1");
+await cacheDel("user:1");
+```
+
+## File storage
+
+The local storage module uses `STORAGE_PATH` or `./storage`:
+
+```javascript
+import { uploadFile, downloadFile, listFiles, deleteFile } from "flet-box-server/tools/storage.js";
+
+const file = await uploadFile("avatars", "profile.jpg", imageBuffer);
+const stream = await downloadFile(file.path);
+const files = await listFiles("avatars");
+await deleteFile(file.path);
+```
+
+Validate file names, sizes, and content types before storing uploads.
+
+## Email
+
+Configure SMTP credentials through environment variables in production. A simple send looks like:
+
+```javascript
+import { sendEmail } from "flet-box-server/tools/email.js";
+
+await sendEmail({
+  sendTo: "user@example.com",
+  title: "Welcome",
+  personalCode: 123456,
+  userName: "Ada",
+});
+```
+
+Never commit passwords or application tokens in source code.
+
+## SMS
+
+Configure Twilio:
+
+```bash
+TWILIO_ACCOUNT_SID=...
+TWILIO_AUTH_TOKEN=...
+TWILIO_PHONE_NUMBER=...
+```
+
+```javascript
+import { sendSMS, sendVerificationCode, verifyPhone } from "flet-box-server/tools/sms.js";
+
+await sendSMS("+123456789", "Your code is 123456");
+const code = await sendVerificationCode("+123456789");
+const valid = await verifyPhone("+123456789", code);
+```
+
+The default verification store is in memory. Use a shared persistent store when scaling.
+
+## PDF
+
+```javascript
+import { generatePDF, savePDF, generateInvoice } from "flet-box-server/tools/pdf.js";
+
+const pdf = await generatePDF("<h1>Hello</h1>", { format: "A4" });
+await savePDF(pdf, "output.pdf");
+
+const invoice = await generateInvoice({
+  number: "INV-001",
+  date: "2026-01-01",
+  client: "Ada Lovelace",
+  items: [{ description: "Consulting", quantity: 2, price: 50 }],
+  total: 100,
+});
+```
+
+PDF generation uses Puppeteer and may require additional system configuration in deployment environments.
+
+## CSV and Excel
+
+```javascript
+import { readCSV, writeCSV, readExcel, writeExcel } from "flet-box-server/tools/csv.js";
+
+const users = await readCSV("users.csv");
+await writeCSV("copy.csv", users);
+const workbookRows = await readExcel("users.xlsx");
+await writeExcel("copy.xlsx", workbookRows);
+```
+
+## Queues
+
+Queues use Redis and Bull:
+
+```javascript
+import { createQueue, addJob, processQueue } from "flet-box-server/tools/queue.js";
+
+createQueue("emails", { attempts: 3, backoff: 5000 });
+
+processQueue("emails", async (job) => {
+  await sendEmail(job.data);
+});
+
+await addJob("emails", {
+  sendTo: "user@example.com",
+  title: "Welcome",
+});
+```
+
+Use queues for slow work that should not block an HTTP request.
+
+## WebSockets
+
+```javascript
+import { createWebSocketServer } from "flet-box-server/tools/webSocket.js";
+
+const wss = createWebSocketServer(3001);
+
+wss.onConnection((ws) => {
+  ws.send(JSON.stringify({ type: "connected" }));
+});
+
+wss.onMessage((ws, message) => {
+  wss.broadcast({ type: "message", data: message });
+});
+```
+
+The server supports connection, message, close, error, broadcast, and room operations.
+
+## Speech and translation
+
+Optional Google Cloud modules provide speech-to-text and text-to-speech. They are `optionalDependencies`, so install the ones you use (`npm install @google-cloud/speech @google-cloud/text-to-speech`); they require cloud credentials and should be configured outside source control.
+
+```javascript
+import { transcribeFile } from "flet-box-server/tools/speechToText.js";
+import { speak } from "flet-box-server/tools/textToSpeech.js";
+import { translate } from "flet-box-server/tools/translator.js";
+
+const text = await transcribeFile("audio.mp3", { language: "en-US" });
+const audio = await speak("Hello", "en");
+const translated = await translate("hello", "es");
+```
+
+## Logging
+
+```javascript
+import { logger } from "flet-box-server/tools/logger.js";
+
+logger.save("logs/app.log");
+logger.info("Server started");
+logger.warn("Slow request", { duration: 800 });
+logger.error("Database error", { code: "DB_ERROR" });
+logger.close();
+```

package/docs/server/deployment.md

@@ -0,0 +1,113 @@
+# Deployment and operations
+
+## Development server
+
+Create a small entry file and run it with Node:
+
+```bash
+node server.js
+```
+
+For automatic restarts, use the package script or nodemon:
+
+```bash
+npm run dev
+```
+
+## Environment variables
+
+Use environment variables for secrets and deployment settings:
+
+```bash
+PORT=3000
+JWT_SECRET=replace-with-a-long-random-secret
+CORS_ORIGINS=https://app.example.com
+REDIS_URL=redis://localhost:6379
+STORAGE_PATH=./storage
+TWILIO_ACCOUNT_SID=...
+TWILIO_AUTH_TOKEN=...
+TWILIO_PHONE_NUMBER=...
+```
+
+Do not commit `.env` files containing secrets.
+
+## Production server
+
+Prefer the secure wrapper:
+
+```javascript
+import { Api, runSecureServer } from "flet-box-server";
+
+const routes = Api({
+  "/health": {
+    GET: () => ({ status: "ok" }),
+  },
+});
+
+runSecureServer(routes, {
+  port: Number(process.env.PORT || 3000),
+  docs: false,
+  rateLimit: { max: 100, windowMs: 60_000 },
+});
+```
+
+Set `docs: true` only when the generated documentation is safe to expose.
+
+## Health check
+
+Add a simple route for monitoring:
+
+```javascript
+"/health": {
+  GET: () => ({
+    status: "ok",
+    timestamp: new Date().toISOString(),
+  }),
+}
+```
+
+## Docker
+
+A minimal Dockerfile:
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+EXPOSE 3000
+CMD ["node", "server.js"]
+```
+
+Build and run:
+
+```bash
+docker build -t flet-box-server .
+docker run --env-file .env -p 3000:3000 flet-box-server
+```
+
+## HTTPS and proxies
+
+Put HTTPS at a trusted reverse proxy such as Nginx, Caddy, or a cloud load balancer. Forward only the headers your proxy controls and configure CORS explicitly.
+
+## Scaling
+
+The default cache, rate limiter, verification store, and security incident list use memory. For multiple server processes, move shared state to Redis or another shared service.
+
+Queues also require Redis to coordinate jobs between workers.
+
+## Production checklist
+
+- Use Node.js 18 or newer.
+- Run `npm ci --omit=dev` in deployment.
+- Set a strong `JWT_SECRET`.
+- Remove hardcoded admin credentials.
+- Disable or protect `/docs` when it exposes internal routes.
+- Set explicit CORS origins.
+- Use HTTPS.
+- Enable validation and rate limiting.
+- Configure Redis for shared cache, sessions, queues, and verification codes.
+- Configure persistent storage and database backups.
+- Monitor `/health`, errors, latency, and resource usage.
+- Do not log passwords, tokens, or private personal data.