omni-rest 0.5.0 → 0.5.1

package/AI/codex/omni-rest/SKILL.md

@@ -14,6 +14,7 @@ For cross-project API work, also read [AI/PORTABLE_API_PLAYBOOK.md](../../../AI/
 - Editing adapters, generators, CLI behavior, or tests.
 - Explaining the repo structure to another agent.
 - Preparing portable instructions for other tools.
+- Integrating omni-rest into a real-world project (NestJS, Express, Next.js, etc.).
 
 ## Working Order
 
@@ -35,3 +36,375 @@ For cross-project API work, also read [AI/PORTABLE_API_PLAYBOOK.md](../../../AI/
 - Prefer code over README text.
 - Preserve existing exports and generated output shapes.
 - Do not rename package entrypoints without a specific request.
+
+---
+
+## Real-World Integration Guide
+
+This section documents how omni-rest is consumed in a production project.
+The reference implementation is `examples/rms/` — a NestJS Restaurant Management System
+with Prisma v7, multi-file schema, and a custom client output path.
+
+### Prisma v7 Compatibility
+
+Prisma v7 made two breaking changes that affect omni-rest:
+
+1. **`Prisma.dmmf` removed** — `@prisma/client` no longer exports the DMMF object.
+   omni-rest's `src/introspect.ts` now guards this access and only uses it for Prisma ≤4.
+   The primary path (`prisma._runtimeDataModel.models`) works for Prisma v5+.
+
+2. **Custom output generates TypeScript source files** — When `output` is set in the
+   generator block, Prisma v7 generates `.ts` files (not a compiled `index.js`).
+   The CLI's `extractRuntimeDataModelFromFile()` now handles:
+   - `internal/class.ts` — the v7 TypeScript config object with embedded model map
+   - `config.runtimeDataModel = JSON.parse("...")` — v7 compiled JS
+   - Inline `runtimeDataModel = { models: {...} }` — Prisma v4/v5 format
+   - `inlineSchema` SDL parsing — last-resort fallback for v7 TS output
+
+3. **Multi-file schema via `prisma.config.ts`** — Prisma v7 supports a `prisma.config.ts`
+   file that points to a schema directory. The CLI now reads this file first and searches
+   all `.prisma` files in the directory for the `output` generator setting.
+
+### Project Structure Pattern
+
+```
+my-app/
+├── prisma/
+│   ├── schema/                    # Multi-file schema (Prisma v7)
+│   │   ├── base.prisma            # generator + datasource
+│   │   ├── 01_auth.prisma
+│   │   └── 02_domain.prisma
+│   └── generated/
+│       └── prisma/                # Custom output path
+│           ├── client.ts          # Main import
+│           └── internal/
+│               └── class.ts      # Contains runtimeDataModel
+├── prisma.config.ts               # Prisma v7 config
+├── src/
+│   ├── prisma/
+│   │   ├── prisma.service.ts      # Wraps PrismaClient for NestJS DI
+│   │   └── prisma.module.ts       # @Global() module
+│   └── omni-rest/
+│       ├── omni-rest.controller.ts  # nestjsController() factory + options
+│       └── omni-rest.module.ts      # NestJS module wiring
+└── src/main.ts                    # Bootstrap with CORS
+```
+
+### PrismaService Pattern (Prisma v7 + NestJS)
+
+Prisma v7 with a custom output path generates TypeScript source files.
+Import directly from the output path — do NOT import from `@prisma/client`:
+
+```ts
+// src/prisma/prisma.service.ts
+import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { PrismaClient } from '../../prisma/generated/prisma/client.js';
+
+@Injectable()
+export class PrismaService implements OnModuleInit, OnModuleDestroy {
+  readonly client: any;
+
+  constructor() {
+    this.client = new (PrismaClient as any)();
+  }
+
+  async onModuleInit() { await this.client.$connect(); }
+  async onModuleDestroy() { await this.client.$disconnect(); }
+
+  [key: string]: any;
+}
+
+// Proxy property access so prismaService.user.findMany() works
+const handler: ProxyHandler<PrismaService> = {
+  get(target, prop) {
+    if (prop in target) return (target as any)[prop];
+    const client = target.client;
+    if (client && prop in client) {
+      const val = (client as any)[prop];
+      return typeof val === 'function' ? val.bind(client) : val;
+    }
+  },
+};
+```
+
+Make it `@Global()` so it's available everywhere without re-importing:
+
+```ts
+// src/prisma/prisma.module.ts
+@Global()
+@Module({ providers: [PrismaService], exports: [PrismaService] })
+export class PrismaModule {}
+```
+
+### omni-rest Options: Production Checklist
+
+When configuring `PrismaRestOptions` for a real project, work through this checklist:
+
+#### 1. Allow List — Explicit Model Exposure
+
+Never expose all models by default. Always set `allow` to the exact list of models
+that external clients should access. Exclude:
+- Auth/session/OTP models (managed by the auth service)
+- Internal audit logs (write-once, managed by middleware)
+- Edge sync queues (internal to the sync engine)
+- Any model with raw secrets or tokens
+
+```ts
+allow: [
+  'brand', 'branch', 'menucategory', 'menuitem',
+  'order', 'orderlineitem', 'payment', 'customer',
+  // ... only what clients actually need
+]
+```
+
+#### 2. Field Guards — Protect Sensitive Fields
+
+Use `fieldGuards` to control field visibility per model:
+
+```ts
+fieldGuards: {
+  // Hide fields that must never leave the server
+  user: {
+    hidden: ['passwordHash'],          // Never in any response
+    readOnly: ['id', 'createdAt'],     // Stripped from write bodies
+  },
+  payment: {
+    hidden: ['gatewayResponse'],       // Raw gateway payload — internal only
+    readOnly: ['processedAt', 'refundedAt'],
+  },
+  // Computed fields that clients must not overwrite
+  order: {
+    readOnly: ['subtotal', 'taxAmount', 'totalAmount', 'orderNumber'],
+  },
+}
+```
+
+Three guard types:
+- `hidden` — field never appears in any GET response AND is stripped from writes
+- `readOnly` — field is stripped from POST/PUT/PATCH bodies (clients can't set it)
+- `writeOnly` — field is accepted in writes but never returned in GET responses
+
+#### 3. Guards — Method-Level Access Control
+
+Use `guards` to block specific HTTP methods on models:
+
+```ts
+// Read-only guard: block all writes
+const readOnlyGuard: GuardFn = ({ method }) =>
+  ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)
+    ? 'This resource is read-only.'
+    : null;
+
+// Blocked guard: block all access
+const blockedGuard: GuardFn = () =>
+  'Access to this resource is not permitted via the REST API.';
+
+guards: {
+  dailyanalyticssnapshot: {
+    POST: readOnlyGuard, PUT: readOnlyGuard,
+    PATCH: readOnlyGuard, DELETE: readOnlyGuard,
+  },
+  loyaltytransaction: {
+    // Immutable ledger — no updates or deletes
+    PUT: readOnlyGuard, PATCH: readOnlyGuard, DELETE: readOnlyGuard,
+  },
+}
+```
+
+For auth-aware guards (JWT-based), inject the request context:
+
+```ts
+guards: {
+  order: {
+    DELETE: async ({ id, body }) => {
+      // In a real app, extract user from request context
+      // and check if they have the MANAGER role
+      return null; // or return error string to block
+    },
+  },
+}
+```
+
+#### 4. Soft Delete
+
+Models with `isActive: Boolean` or `deletedAt: DateTime` get soft-delete automatically
+when `softDelete: true` is set. DELETE sets `isActive = false` or `deletedAt = new Date()`
+instead of destroying the record. GET list queries automatically filter out soft-deleted records.
+
+```ts
+softDelete: true,
+// Optional: override the auto-detected field name
+// softDeleteField: 'archivedAt',
+```
+
+Models in the RMS project that benefit from soft delete:
+- `Branch` (isActive)
+- `RestaurantTable` (isActive)
+- `MenuItem` (isAvailable — use explicit softDeleteField)
+- `Customer` (isActive)
+- `TaxRule` (isActive)
+- `ModifierOption` (isAvailable)
+
+#### 5. Complexity Limits
+
+Protect against abusive queries that join many relations or request huge result sets:
+
+```ts
+complexity: {
+  maxScore: 50,
+  rules: {
+    perInclude: 10,   // Each ?include=relation costs 10 points
+    perFilter: 2,     // Each filter key costs 2 points
+    perSort: 1,       // Each sort field costs 1 point
+    perLimit100: 5,   // Each 100 records requested costs 5 points
+  },
+},
+```
+
+#### 6. Pagination
+
+```ts
+defaultLimit: 25,   // Default page size
+maxLimit: 200,      // Hard cap — clients can't request more
+paginationMode: 'offset',  // or 'cursor' for large datasets
+envelope: true,     // Wrap in { data: [...], meta: { total, page, limit, totalPages } }
+```
+
+Use cursor pagination for high-volume models (orders, stock movements, audit logs)
+where offset pagination becomes slow at large offsets.
+
+#### 7. Aggregation Endpoints
+
+When `features.aggregation: true`, omni-rest exposes:
+- `GET /api/order/aggregate?_count=*&_sum=totalAmount` — aggregate stats
+- `GET /api/order/groupBy?by=status&_count=*` — group by field
+
+These are powerful for analytics dashboards. Disable them on sensitive models
+by setting `features: { aggregation: false }` or using a guard.
+
+#### 8. SSE Real-Time Subscriptions
+
+Every exposed model gets a `GET /api/:model/subscribe` SSE endpoint automatically.
+The POS tablet can subscribe to order updates without polling:
+
+```ts
+const es = new EventSource('/api/order/subscribe');
+es.onmessage = (e) => {
+  const { event, model, record } = JSON.parse(e.data);
+  if (event === 'create') addOrderToKDS(record);
+  if (event === 'update') updateOrderStatus(record);
+};
+```
+
+Tune the polling interval to balance freshness vs. DB load:
+
+```ts
+subscription: {
+  pollInterval: 500,        // 500ms for POS (low latency)
+  heartbeatInterval: 30_000, // 30s keepalive
+},
+```
+
+### NestJS Wiring
+
+```ts
+// src/omni-rest/omni-rest.controller.ts
+import { nestjsController } from 'omni-rest';
+import { PrismaService } from '../prisma/prisma.service';
+
+let _prisma: PrismaService | null = null;
+function getPrisma() {
+  if (!_prisma) {
+    _prisma = new PrismaService();
+    void _prisma.onModuleInit();
+  }
+  return _prisma;
+}
+
+export const OmniRestDynamicModule = nestjsController(
+  getPrisma(),
+  omniRestOptions,
+  'api',  // URL prefix → /api/:model
+);
+
+// src/omni-rest/omni-rest.module.ts
+@Module({
+  imports: [PrismaModule],
+  controllers: [OmniRestDynamicModule],
+})
+export class OmniRestModule {}
+
+// src/app.module.ts
+@Module({
+  imports: [PrismaModule, OmniRestModule],
+  // ...
+})
+export class AppModule {}
+```
+
+### CLI Usage with Prisma v7
+
+The CLI reads `prisma.config.ts` automatically to find the schema and output path:
+
+```bash
+# From the project root (where prisma.config.ts lives)
+npx omni-rest generate          # Zod schemas + OpenAPI spec
+npx omni-rest generate:zod      # Zod schemas only → src/schemas.generated.ts
+npx omni-rest generate:openapi  # OpenAPI spec → openapi.json
+npx omni-rest generate:config   # omni-rest.config.json for the frontend client
+```
+
+For Prisma v7 with multi-file schema + custom output, the CLI:
+1. Reads `prisma.config.ts` to find `schema: "prisma/schema"` (directory)
+2. Scans all `.prisma` files in that directory for `output = "..."` in the generator block
+3. Reads `prisma/generated/prisma/internal/class.ts` and extracts the model map
+4. Generates schemas without requiring a DB connection
+
+### API Usage Examples
+
+```bash
+# List all active branches with pagination
+GET /api/branch?page=1&limit=25
+
+# Filter orders by status and branch
+GET /api/order?status=PENDING&branchId=clxyz123&orderBy=createdAt:desc
+
+# Include related line items
+GET /api/order/clxyz123?include=lineItems
+
+# Aggregate: total revenue by branch today
+GET /api/dailyanalyticssnapshot/aggregate?_sum=totalRevenue&branchId=clxyz123
+
+# Group orders by status
+GET /api/order/groupBy?by=status&_count=*
+
+# Soft delete a menu item (sets isAvailable=false)
+DELETE /api/menuitem/clxyz456
+
+# Bulk create menu items
+POST /api/menuitem/bulk
+[{ "name": "Zinger Burger", "basePrice": 450, ... }, ...]
+
+# Real-time order updates (SSE)
+GET /api/order/subscribe
+```
+
+### Security Considerations
+
+1. **Never expose auth models** — `User`, `Session`, `OtpCode`, `UserAuthProvider`,
+   `RoleAssignment`, `PermissionOverride` should never be in the `allow` list.
+   These are managed by the dedicated auth service with proper password hashing,
+   token rotation, and rate limiting.
+
+2. **Guard write operations on financial models** — `Payment`, `Shift`, `AppliedDiscount`
+   should require manager-level auth before POST/PUT/PATCH/DELETE.
+
+3. **Hide all token/hash fields** — `refreshToken`, `codeHash`, `passwordHash`,
+   `accessToken`, `gatewayResponse` must be in `hidden` field guards.
+
+4. **Rate limit the API** — Use the `rateLimit` option with Redis or an in-memory
+   counter to prevent abuse of bulk endpoints and aggregation queries.
+
+5. **Validate writes with Zod** — Run `npx omni-rest generate:zod` to generate
+   Zod schemas, then use `withValidation()` middleware to validate request bodies
+   before they reach Prisma.

package/dist/adapters/express.js

@@ -29,7 +29,7 @@ function getModels(prisma) {
     try {
       const prismaModule = __require("@prisma/client");
       const dmmfModels = prismaModule?.Prisma?.dmmf?.datamodel?.models;
-      if (dmmfModels) {
+      if (Array.isArray(dmmfModels) && dmmfModels.length > 0) {
         raw = dmmfModels;
       }
     } catch {