@nage-api/contracts 1.0.0-beta.2

package/dist/pagination.types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pagination contracts (PLAN.md §16.1).
+ *
+ * The legacy `offset` / `limit` / `count` field names are preserved for
+ * migration familiarity, but nested under `meta.pagination` in the envelope.
+ */
+/** Offset pagination requested by a client. */
+export interface PaginationInput {
+    readonly offset?: number;
+    readonly limit?: number;
+}
+/** Offset pagination reported back to a client. */
+export interface PaginationMeta {
+    readonly offset: number;
+    readonly limit: number;
+    /** Total number of records matching the query, ignoring offset/limit. */
+    readonly count: number;
+}
+/** A page of records plus its pagination metadata. */
+export interface Paginated<T> {
+    readonly records: readonly T[];
+    readonly pagination: PaginationMeta;
+}
+/**
+ * Cursor pagination for large result sets. Replaces the legacy unbounded
+ * `limit: -1` (PLAN.md §12), which is rejected by the query policy.
+ */
+export interface CursorPaginationInput {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface CursorPaginationMeta {
+    readonly nextCursor: string | null;
+    readonly limit: number;
+    readonly hasMore: boolean;
+}
+export interface CursorPaginated<T> {
+    readonly records: readonly T[];
+    readonly pagination: CursorPaginationMeta;
+}
+//# sourceMappingURL=pagination.types.d.ts.map

package/dist/pagination.types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Pagination contracts (PLAN.md §16.1).
+ *
+ * The legacy `offset` / `limit` / `count` field names are preserved for
+ * migration familiarity, but nested under `meta.pagination` in the envelope.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=pagination.types.js.map

package/dist/query.types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The typed query DSL (PLAN.md §12, §14.2, §16.2).
+ *
+ * The legacy framework forwarded client-supplied `$`-operators straight to the
+ * ORM and accepted `limit: -1`. Here the DSL is:
+ *   - **typed** — `where`/`sort`/`select` keys are constrained to `keyof TEntity`
+ *   - **allow-listed** — a per-model `QueryPolicy` declares which fields and
+ *     operators a client may use
+ *   - **bounded** — `maxLimit` is enforced by the driver, never by the client
+ */
+import type { FieldName, Id } from './common.types.js';
+/** Comparison operators a driver must support. Named, not `$`-prefixed. */
+export type ComparisonOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'ilike' | 'between' | 'isNull';
+/** Operator object for a single field of type `V`. */
+export interface FieldCondition<V> {
+    readonly eq?: V;
+    readonly ne?: V;
+    readonly gt?: V;
+    readonly gte?: V;
+    readonly lt?: V;
+    readonly lte?: V;
+    readonly in?: readonly V[];
+    readonly nin?: readonly V[];
+    readonly like?: string;
+    readonly ilike?: string;
+    readonly between?: readonly [V, V];
+    readonly isNull?: boolean;
+}
+/** A bare value is shorthand for `{ eq: value }`. */
+export type WhereValue<V> = V | FieldCondition<V>;
+/** Typed `where` clause with logical composition. */
+export type Where<TEntity> = {
+    readonly [K in keyof TEntity]?: WhereValue<TEntity[K]>;
+} & {
+    readonly and?: readonly Where<TEntity>[];
+    readonly or?: readonly Where<TEntity>[];
+    readonly not?: Where<TEntity>;
+};
+export type SortDirection = 'asc' | 'desc';
+/** Ordered sort instructions; array order is significant. */
+export type Sort<TEntity> = readonly (readonly [
+    field: FieldName<TEntity>,
+    direction: SortDirection
+])[];
+/** Free-text search across the model's configured `searchFields`. */
+export interface SearchInput {
+    readonly term: string;
+    /** Restrict the search to a subset of the model's searchable fields. */
+    readonly fields?: readonly string[];
+}
+/** Relation to eager-load. Nested relations use dot paths (max depth is policed). */
+export type Populate = string;
+/** A named, server-defined query fragment (replaces client-supplied scopes). */
+export type ScopeName = string;
+/** The full query a repository accepts. Every member is optional. */
+export interface Query<TEntity> {
+    readonly where?: Where<TEntity>;
+    readonly select?: readonly FieldName<TEntity>[];
+    readonly sort?: Sort<TEntity>;
+    readonly populate?: readonly Populate[];
+    readonly scope?: readonly ScopeName[];
+    readonly search?: SearchInput;
+    readonly offset?: number;
+    readonly limit?: number;
+    /** Include soft-deleted rows. Requires an explicit permission (PLAN.md §14.2). */
+    readonly withDeleted?: boolean;
+    /** Cursor pagination; mutually exclusive with `offset`. */
+    readonly cursor?: string;
+}
+/**
+ * Per-model allow-list enforced before a query reaches the driver.
+ * Anything not listed is rejected with `INVALID_QUERY`.
+ */
+export interface QueryPolicy<TEntity> {
+    readonly filterable: readonly FieldName<TEntity>[];
+    readonly sortable: readonly FieldName<TEntity>[];
+    readonly selectable: readonly FieldName<TEntity>[];
+    readonly searchable: readonly FieldName<TEntity>[];
+    readonly populatable: readonly Populate[];
+    readonly scopes: readonly ScopeName[];
+    readonly operators: readonly ComparisonOperator[];
+    /** Hard ceiling on `limit`. There is no unbounded query. */
+    readonly maxLimit: number;
+    readonly defaultLimit: number;
+    /** Maximum depth allowed in dotted `populate` paths. */
+    readonly maxPopulateDepth: number;
+}
+/** Locator for a single record. */
+export interface ByIdQuery<TEntity> extends Omit<Query<TEntity>, 'offset' | 'limit' | 'cursor'> {
+    readonly id: Id;
+}
+//# sourceMappingURL=query.types.d.ts.map

package/dist/query.types.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * The typed query DSL (PLAN.md §12, §14.2, §16.2).
+ *
+ * The legacy framework forwarded client-supplied `$`-operators straight to the
+ * ORM and accepted `limit: -1`. Here the DSL is:
+ *   - **typed** — `where`/`sort`/`select` keys are constrained to `keyof TEntity`
+ *   - **allow-listed** — a per-model `QueryPolicy` declares which fields and
+ *     operators a client may use
+ *   - **bounded** — `maxLimit` is enforced by the driver, never by the client
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=query.types.js.map

package/dist/repository.types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Engine-agnostic data ports (PLAN.md §14.1).
+ *
+ * `@nage-api/data-sql` and `@nage-api/data-mongo` implement these and are validated by a
+ * single shared conformance suite. Application code depends on the port, never
+ * on a driver — which is what makes the engine choice a scaffold-time decision
+ * instead of a runtime `if (engine === …)` branch.
+ */
+import type { DeepPartial, Id } from './common.types.js';
+import type { Paginated, CursorPaginated } from './pagination.types.js';
+import type { ByIdQuery, Query } from './query.types.js';
+import type { DeleteMode, ModelDescriptor } from './entity.types.js';
+/** Opaque handle to an open transaction; its shape is driver-specific. */
+export interface TxContext {
+    readonly id: string;
+    readonly driver: string;
+}
+/** Options accepted by every write operation. */
+export interface WriteOptions {
+    readonly tx?: TxContext;
+}
+export interface DeleteOptions extends WriteOptions {
+    readonly mode?: DeleteMode;
+}
+/** Outcome of a bulk write. */
+export interface BulkResult<TEntity> {
+    readonly affected: number;
+    readonly records: readonly TEntity[];
+}
+/**
+ * The contract every driver implements for a single model.
+ *
+ * Reads take a typed `Query`; writes take `DeepPartial<TEntity>` and an optional
+ * transaction context so a `UnitOfWork` can make multi-model work atomic.
+ */
+export interface RepositoryPort<TEntity> {
+    readonly descriptor: ModelDescriptor<TEntity>;
+    findAll(query?: Query<TEntity>): Promise<Paginated<TEntity>>;
+    findByCursor(query?: Query<TEntity>): Promise<CursorPaginated<TEntity>>;
+    findOne(query?: Query<TEntity>): Promise<TEntity | null>;
+    findById(id: Id, query?: Omit<ByIdQuery<TEntity>, 'id'>): Promise<TEntity | null>;
+    exists(query?: Query<TEntity>): Promise<boolean>;
+    count(query?: Query<TEntity>): Promise<number>;
+    create(data: DeepPartial<TEntity>, options?: WriteOptions): Promise<TEntity>;
+    update(id: Id, data: DeepPartial<TEntity>, options?: WriteOptions): Promise<TEntity>;
+    delete(id: Id, options?: DeleteOptions): Promise<void>;
+    restore(id: Id, options?: WriteOptions): Promise<TEntity>;
+    bulkCreate(data: readonly DeepPartial<TEntity>[], options?: WriteOptions): Promise<BulkResult<TEntity>>;
+    bulkUpdate(query: Query<TEntity>, data: DeepPartial<TEntity>, options?: WriteOptions): Promise<BulkResult<TEntity>>;
+    bulkDelete(query: Query<TEntity>, options?: DeleteOptions): Promise<number>;
+}
+/**
+ * Transaction boundary. Lifecycle hooks run **inside** the transaction, so a
+ * failing `doAfterCreate` rolls the write back (PLAN.md §14.2).
+ */
+export interface UnitOfWork {
+    run<TResult>(fn: (tx: TxContext) => Promise<TResult>): Promise<TResult>;
+}
+/** Health probe feeding `/health/ready` (PLAN.md §21). */
+export interface DataSourceHealth {
+    ping(): Promise<boolean>;
+    readonly driver: string;
+}
+/** Pluggable session storage so auth is not hard-wired to one engine (§15.1). */
+export interface KeyValueStore<TValue> {
+    get(key: string): Promise<TValue | null>;
+    set(key: string, value: TValue, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+//# sourceMappingURL=repository.types.d.ts.map

package/dist/repository.types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Engine-agnostic data ports (PLAN.md §14.1).
+ *
+ * `@nage-api/data-sql` and `@nage-api/data-mongo` implement these and are validated by a
+ * single shared conformance suite. Application code depends on the port, never
+ * on a driver — which is what makes the engine choice a scaffold-time decision
+ * instead of a runtime `if (engine === …)` branch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=repository.types.js.map

package/dist/response.types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The single API response envelope (PLAN.md §16.1).
+ *
+ * Controllers `return data`; the global `ResponseInterceptor` and
+ * `AllExceptionsFilter` in `@nage-api/core` build these shapes. No controller ever
+ * touches `res` — that was the legacy `@Res()` escape hatch this replaces.
+ */
+import type { ErrorPayload } from './error.types.js';
+import type { PaginationMeta, CursorPaginationMeta } from './pagination.types.js';
+/** Metadata attached to every response, successful or not. */
+export interface ResponseMeta {
+    readonly requestId: string;
+    readonly timestamp: string;
+    /** API version that served the request (`x-application-version`). */
+    readonly version?: number;
+    readonly pagination?: PaginationMeta | CursorPaginationMeta;
+}
+/** Successful response. Historically produced by `core.responses.ts#Result`. */
+export interface SuccessResponse<TData> {
+    readonly success: true;
+    readonly data: TData;
+    readonly meta: ResponseMeta;
+}
+/** Failed response. `error.message` is always client-safe. */
+export interface ErrorResponse {
+    readonly success: false;
+    readonly error: ErrorPayload;
+    readonly meta: ResponseMeta;
+}
+/** Discriminated union a typed HTTP client can narrow on `success`. */
+export type ApiResponse<TData> = SuccessResponse<TData> | ErrorResponse;
+/**
+ * Successful envelope, kept under the legacy name for migration familiarity
+ * (PLAN.md §13 — "typed `Result<TData>` replaces `any`").
+ */
+export type Result<TData> = SuccessResponse<TData>;
+/** A list response: `data` is the page, `meta.pagination` carries the counters. */
+export interface PaginatedResponse<TData> extends SuccessResponse<readonly TData[]> {
+    readonly meta: ResponseMeta & {
+        readonly pagination: PaginationMeta | CursorPaginationMeta;
+    };
+}
+//# sourceMappingURL=response.types.d.ts.map

package/dist/response.types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * The single API response envelope (PLAN.md §16.1).
+ *
+ * Controllers `return data`; the global `ResponseInterceptor` and
+ * `AllExceptionsFilter` in `@nage-api/core` build these shapes. No controller ever
+ * touches `res` — that was the legacy `@Res()` escape hatch this replaces.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=response.types.js.map

package/dist/security.types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Security ports and findings (PLAN.md §12).
+ *
+ * `@nage-api/core` implements the in-process versions; `@nage-api/cache` can back the
+ * rate-limit store with Redis, and `@nage-api/cli`'s `doctor` renders the findings —
+ * none of them importing each other.
+ */
+/** Outcome of consuming one unit of a rate-limit budget. */
+export interface RateLimitResult {
+    readonly allowed: boolean;
+    /** Requests permitted in the current window. */
+    readonly limit: number;
+    /** Requests still available; `0` once the budget is spent. */
+    readonly remaining: number;
+    /** Epoch milliseconds at which the window resets. */
+    readonly resetAt: number;
+    /** Seconds a rejected caller should wait; the `Retry-After` value. */
+    readonly retryAfterSeconds: number;
+}
+/**
+ * Counter store behind the rate-limit guard. The default implementation is
+ * per-process; a multi-instance deployment supplies a shared one — through
+ * `NageCoreModule.forRoot(config, { rateLimitStore })` — so a limit of 100 means
+ * 100 across the fleet rather than 100 per pod. No shared implementation ships.
+ */
+export interface RateLimitStore {
+    readonly name: string;
+    /** Record one request against `key` and report the resulting budget. */
+    consume(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
+    /** Clear a key — used after a successful login resets a failure counter. */
+    reset(key: string): Promise<void>;
+}
+/** How much a security finding matters. */
+export type SecuritySeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+/** Stable identifiers so a finding can be suppressed or tracked over time. */
+export type SecurityFindingCode = 'SEC_CORS_WILDCARD' | 'SEC_CORS_WILDCARD_WITH_CREDENTIALS' | 'SEC_HELMET_DISABLED' | 'SEC_CSP_DISABLED' | 'SEC_HSTS_DISABLED' | 'SEC_TLS_NO_VERIFY' | 'SEC_TLS_DISABLED' | 'SEC_VALIDATION_DISABLED' | 'SEC_VALIDATION_PERMISSIVE' | 'SEC_RATE_LIMIT_DISABLED' | 'SEC_UNBOUNDED_QUERY_LIMIT' | 'SEC_MIGRATIONS_ON_BOOT' | 'SEC_DEBUG_LOGGING' | 'SEC_WEAK_JWT_ALGORITHM' | 'SEC_LONG_ACCESS_TTL' | 'SEC_REFRESH_ROTATION_DISABLED' | 'SEC_REUSE_DETECTION_DISABLED' | 'SEC_WEAK_PASSWORD_POLICY' | 'SEC_WEAK_SECRET' | 'SEC_MISSING_SECRET' | 'SEC_SHUTDOWN_HOOKS_DISABLED' | 'SEC_NO_REQUEST_TIMEOUT' | 'SEC_LEGACY_PATTERN';
+export interface SecurityFinding {
+    readonly code: SecurityFindingCode;
+    readonly severity: SecuritySeverity;
+    /** Config path or file location the finding refers to, e.g. `http.cors.origins`. */
+    readonly location: string;
+    /** What is wrong. Never contains a secret value. */
+    readonly message: string;
+    /** What to do about it. */
+    readonly remediation: string;
+}
+//# sourceMappingURL=security.types.d.ts.map

package/dist/security.types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Security ports and findings (PLAN.md §12).
+ *
+ * `@nage-api/core` implements the in-process versions; `@nage-api/cache` can back the
+ * rate-limit store with Redis, and `@nage-api/cli`'s `doctor` renders the findings —
+ * none of them importing each other.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=security.types.js.map

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@nage-api/contracts",
+  "version": "1.0.0-beta.2",
+  "description": "Pure TypeScript contracts for the @nage-api framework — types only, no runtime, no Nest",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "rimraf": "6.1.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}