@airoom/nextmin-node 0.1.0

package/LICENSE

@@ -0,0 +1,49 @@
+Nextmin Proprietary License v1.0
+
+Copyright (c) 2025 GSCodes
+All rights reserved.
+
+1. Definitions
+“Software” means the package and all accompanying files under the package name(s) @airoom/nextmin-react and @airoom/nextmin-node, including any updates provided by Licensor.
+“Licensor” means GSCodes.
+“Licensee” means the person or entity that obtains the Software.
+
+2. Grant of License
+Subject to full compliance with this License, Licensor grants Licensee a limited, non-exclusive, non-transferable, non-sublicensable license to:
+  a) install and use the Software internally, solely for evaluating or running Licensee’s own applications; and
+  b) make a reasonable number of copies solely for internal backup and archival purposes.
+
+3. Restrictions
+Except as expressly permitted in Section 2, Licensee must NOT:
+  a) copy, publish, distribute, sell, rent, lease, lend, sublicense, or otherwise make the Software available to any third party;
+  b) modify, translate, adapt, create derivative works of, or merge the Software with other software;
+  c) reverse engineer, decompile, disassemble, or otherwise attempt to derive source code or underlying ideas, except to the extent such restrictions are expressly prohibited by applicable law;
+  d) remove, obscure, or alter any proprietary notices or markings; or
+  e) use the Software to train, fine-tune, or improve any artificial intelligence or machine learning model.
+
+4. Ownership
+The Software is licensed, not sold. Licensor retains all right, title, and interest in and to the Software, including all intellectual property rights and all copies.
+
+5. Confidentiality
+The Software and any non-public information provided by Licensor shall be treated as confidential and not disclosed to any third party without Licensor’s prior written consent, except as required by law.
+
+6. Term and Termination
+This License is effective until terminated. Licensor may terminate this License immediately upon notice if Licensee breaches any term. Upon termination, Licensee must cease all use and destroy all copies of the Software. Sections 3–10 survive termination.
+
+7. Updates; No Support Obligation
+Licensor may, but is not obligated to, provide updates, bug fixes, or support. Any updates are governed by this License unless accompanied by a different license.
+
+8. No Warranty
+THE SOFTWARE IS PROVIDED “AS IS” AND “AS AVAILABLE,” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. USE IS AT LICENSEE’S SOLE RISK.
+
+9. Limitation of Liability
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR ANY LOSS OF PROFITS, REVENUE, DATA, GOODWILL, OR BUSINESS INTERRUPTION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. LICENSOR’S TOTAL LIABILITY FOR ALL CLAIMS SHALL NOT EXCEED THE AMOUNT PAID BY LICENSEE FOR THE SOFTWARE (IF ANY) IN THE TWELVE (12) MONTHS PRECEDING THE CLAIM.
+
+10. Governing Law; Venue
+This License is governed by the laws of State of California, USA, without regard to its conflict of laws principles. The parties submit to the exclusive jurisdiction and venue of the courts located in San Francisco County, California, USA.
+
+11. Commercial Licensing
+For commercial use, redistribution, or other rights not expressly granted, contact: tareqaziz0065@gmail.com.
+
+12. Entire Agreement
+This License constitutes the entire agreement with respect to the Software and supersedes all prior or contemporaneous agreements or understandings on the subject matter.

package/README.md

@@ -0,0 +1,178 @@
+# @airoom/nextmin-node
+
+Schema‑driven Node.js toolkit that turns a JSON schema into a secure, policy‑aware REST API with authentication, CRUD, relationship querying, and file uploads. Pair it with `@airoom/nextmin-react` to get a fully‑featured Admin Panel in minutes.
+
+- “From JSON schema to REST API + Admin”
+- 1 month → 1 hour
+
+## Highlights
+
+- Express router factory: mount a complete REST API in a few lines
+- Auth built in: register, login, me, change‑password, forgot‑password
+- CRUD per model with read masks, write restrictions, and role/owner policies
+- Advanced list endpoint: filter, multi‑field search, date ranges, multi‑field sort, paginate
+- Relationship endpoints: forward and reverse lookups without autopopulate
+- Schemas hot‑reload during development; automatic model wiring
+- File uploads via pluggable storage (e.g., S3/MinIO); delete by key
+- Database adapters: MongoDB (with index sync) and in‑memory for tests
+- Emits a trusted API key stored in your Settings model for client access
+
+## Installation
+
+```bash
+# npm
+npm install @airoom/nextmin-node
+
+# yarn
+yarn add @airoom/nextmin-node
+
+# pnpm
+pnpm add @airoom/nextmin-node
+```
+
+## Quick start (Express + Mongo + S3 optional)
+
+```ts
+import dotenv from 'dotenv';
+import express from 'express';
+import http from 'http';
+import {
+  createNextMinRouter,
+  MongoAdapter,
+  S3FileStorageAdapter,
+} from '@airoom/nextmin-node';
+import cors from 'cors';
+
+dotenv.config();
+
+async function start() {
+  const app = express();
+  const server = http.createServer(app); // pass this to the router for sockets
+
+  app.use(cors());
+
+  // 1) Database
+  const db = new MongoAdapter(process.env.MONGO_URL!, process.env.MONGO_DB!);
+  await db.connect();
+
+  // 2) Optional: file storage adapter (S3/MinIO)
+  const files = new S3FileStorageAdapter({
+    bucket: process.env.S3_BUCKET!,
+    region: process.env.S3_REGION!,
+    credentials:
+      process.env.S3_ACCESS_KEY_ID && process.env.S3_SECRET_ACCESS_KEY
+        ? {
+            accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+            secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
+          }
+        : undefined,
+    endpoint: process.env.S3_ENDPOINT || undefined,
+    forcePathStyle: /^(1|true|yes)$/i.test(process.env.S3_FORCE_PATH_STYLE || ''),
+    defaultACL: (process.env.S3_DEFAULT_ACL as any) || 'public-read',
+    publicBaseUrl: process.env.S3_PUBLIC_BASE_URL || undefined,
+  });
+
+  // 3) Mount NextMin REST router
+  const router = createNextMinRouter({ dbAdapter: db, server, fileStorageAdapter: files });
+  app.use('/rest', router);
+
+  // 4) Listen with the same server instance
+  const port = Number(process.env.PORT || 8081);
+  server.listen(port, () => console.log(`REST ready: http://localhost:${port}/rest`));
+}
+
+start().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+```
+
+## REST endpoints (summary)
+
+Base: `/rest`
+
+- Schemas: `GET /_schemas` → public schema list (requires x-api-key)
+- Auth (users):
+  - `POST /auth/users/register`
+  - `POST /auth/users/login`
+  - `GET  /auth/users/me`
+  - `POST /auth/users/change-password`
+  - `POST /auth/users/forgot-password`
+- Generic CRUD per model (model names are lowercase):
+  - `POST   /:model`
+  - `GET    /:model` (query: page, limit, q, searchKey(s), searchMode, dateFrom/to/key, sort, sortType)
+  - `GET    /:model/:id`
+  - `PUT    /:model/:id` (or PATCH depending on client)
+  - `DELETE /:model/:id`
+- Relationship queries:
+  - Forward: `GET /find/:container/:refField/:id`
+  - Reverse: `GET /find/reverse/:target/:byField/:id`
+- Files (when file storage adapter is configured):
+  - Upload: `POST /files` (multipart form, fields named `file`)
+  - Delete: `DELETE /files/:key(*)`
+
+See full examples in documentation and the `examples/node` app inside this monorepo.
+
+## Headers and auth
+
+- All requests must include the API key header: `x-api-key: <YOUR_API_KEY>`
+- Authenticated routes also require: `Authorization: Bearer <JWT>`
+
+Where do I find my API key?
+
+- On first run, the server initializes default data and stores a trusted `apiKey` in your Settings collection/table.
+- Copy that value into your clients. You can also preseed it by setting `NEXTMIN_API_KEY` before the first boot.
+
+## Configuration (env)
+
+Application
+
+- `APP_MODE`: development | production (affects dev features)
+- `JWT_SECRET`: secret used to sign JWTs
+
+Database
+
+- `MONGO_URL`: e.g. mongodb://localhost:27017
+- `MONGO_DB`: database name
+
+File storage (optional)
+
+- `S3_BUCKET`, `S3_REGION`
+- `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`
+- `S3_ENDPOINT` (for MinIO or custom)
+- `S3_FORCE_PATH_STYLE` (true for MinIO)
+- `S3_DEFAULT_ACL` (e.g., public-read)
+- `S3_PUBLIC_BASE_URL` (CDN/base URL for public links)
+
+Frontend integration
+
+- `NEXT_PUBLIC_GOOGLE_MAPS_KEY` (used by address autocomplete within the Admin UI)
+
+## Default super admin (after setup)
+
+After the initial setup, you can sign in with the default super user and should immediately change the password:
+
+- Email: super@example.com
+- Username: superadmin
+- Password: supersecurepassword
+
+Change it right after the first login.
+
+## TypeScript
+
+Types are bundled. Example import:
+
+```ts
+import type { APIRouterOptions } from '@airoom/nextmin-node';
+```
+
+## Troubleshooting
+
+- 401 Unauthorized: verify `x-api-key` matches `Settings.apiKey` and that JWT is present for protected routes.
+- CORS issues: allow your frontend origin in development.
+- Sorting/filters: unknown fields are ignored; ensure you pass existing attribute names.
+- Relationship endpoints: confirm your schema uses proper `ref` fields.
+
+## License
+
+Licensed under the Nextmin Proprietary License. © 2025 GSCodes. For commercial licensing or extended rights, contact: tareqaziz0065@gmail.com.

package/dist/api/apiRouter.d.ts

@@ -0,0 +1,65 @@
+import express from 'express';
+import type { Server as HttpServer } from 'http';
+import { DatabaseAdapter } from '../database/DatabaseAdapter';
+import type { FileStorageAdapter } from '../files/FileStorageAdapter';
+export interface APIRouterOptions {
+    dbAdapter: DatabaseAdapter;
+    server?: HttpServer;
+    fileStorageAdapter?: FileStorageAdapter;
+}
+export declare class APIRouter {
+    private router;
+    private models;
+    private dbAdapter;
+    private jwtSecret;
+    private trustedApiKey;
+    private schemaLoader;
+    private isDevelopment;
+    private findRoutesMounted;
+    private authRoutesInitialized;
+    private schemasRouteRegistered;
+    private registeredModels;
+    private liveSchemas;
+    private notFoundHandler?;
+    private fileStorage?;
+    constructor(options: APIRouterOptions);
+    getRouter(): express.Router;
+    private wireSchemaHotReload;
+    private syncAllIndexes;
+    private diffRemovedModels;
+    private setLiveSchemas;
+    private rebuildModels;
+    private mountSchemasEndpointOnce;
+    private mountRoutes;
+    private getSchema;
+    private getModel;
+    private setupRoutes;
+    private mountFindRoutes;
+    private fileAuthMiddleware;
+    /** Mount generic file endpoints under this router */
+    private setupFileRoutes;
+    /** uploads/YYYY/MM/DD */
+    private shortFolder;
+    /** small, URL-safe uid */
+    private shortUid;
+    private normalizeAttrType;
+    private optionalAuthMiddleware;
+    private pickAuthFor;
+    private getUserRoleFromReq;
+    private normalizeRoleName;
+    private setupAuthRoutes;
+    /**
+     * Validate required fields.
+     * - create: field must exist and be non-empty (not null/undefined/'').
+     * - update: only validate fields that are explicitly present in the payload;
+     *           absence means "unchanged".
+     */
+    private validateRequiredFields;
+    private handleWriteError;
+    private setupNotFoundMiddleware;
+    private ensureNotFoundLast;
+    private apiKeyMiddleware;
+    private validateRoleValue;
+    private authenticateMiddleware;
+    private checkUniqueFields;
+}