@datrix/api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 datrix Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# @datrix/api
+
+HTTP REST API plugin for Datrix. Turns any Datrix instance into a fully-featured REST API — auto-generates CRUD routes for every schema, handles JWT and session authentication, RBAC permissions, and optionally manages file uploads via [`@datrix/api-upload`](../api-upload/README.md).
+
+## Installation
+
+```bash
+pnpm add @datrix/api
+```
+
+## Setup
+
+```typescript
+import { defineConfig } from "datrix-core"
+import { ApiPlugin } from "@datrix/api"
+
+export default defineConfig(() => ({
+  adapter,
+  schemas,
+  plugins: [
+    new ApiPlugin({
+      prefix:           "/api",  // default: "/api"
+      defaultPageSize:  25,      // default: 25
+      maxPageSize:      100,     // default: 100
+      maxPopulateDepth: 5,       // default: 5
+      excludeSchemas:   [],      // always excludes _datrix and _datrix_migrations
+    }),
+  ],
+}))
+```
+
+## Request handling
+
+### `handleRequest`
+
+```typescript
+import { handleRequest } from "@datrix/api"
+
+handleRequest(datrix: IDatrix, request: Request): Promise<Response>
+```
+
+Main entry point. Routes to the appropriate handler (auth, CRUD, or upload). Always returns a `Response`, never throws.
+
+#### Next.js App Router
+
+```typescript
+import datrix from "@/datrix.config"
+import { handleRequest } from "@datrix/api"
+
+async function handler(request: Request): Promise<Response> {
+  return handleRequest(await datrix(), request)
+}
+
+export const GET = handler
+export const POST = handler
+export const PATCH = handler
+export const PUT = handler
+export const DELETE = handler
+```
+
+#### Express
+
+```typescript
+import express from "express"
+import { handleRequest, toWebRequest, sendWebResponse } from "@datrix/api"
+
+const app = express()
+app.use(express.raw({ type: "*/*" }))
+
+app.all("*", async (req, res) => {
+  const request  = toWebRequest(req)
+  const response = await handleRequest(await datrix(), request)
+  await sendWebResponse(res, response)
+})
+```
+
+`toWebRequest` / `sendWebResponse` work with any Node.js-style request/response — Fastify, Koa, raw `http.createServer`.
+
+## Auto-generated CRUD routes
+
+For every registered schema:
+
+| Method   | Path               | Description                              |
+| -------- | ------------------ | ---------------------------------------- |
+| `GET`    | `/api/:schema`     | List records — pagination, filtering, sorting, populate |
+| `GET`    | `/api/:schema/:id` | Get a single record                      |
+| `POST`   | `/api/:schema`     | Create a record                          |
+| `PATCH`  | `/api/:schema/:id` | Update a record                          |
+| `DELETE` | `/api/:schema/:id` | Delete a record                          |
+
+The `:schema` segment matches the schema's table name (e.g. schema `"product"` → `/api/products`).
+
+### Filtering, sorting, pagination
+
+Pass query parameters as a serialized `ParsedQuery` object. Use `queryToParams` to build them:
+
+```typescript
+import { queryToParams } from "@datrix/api"
+
+const qs = queryToParams({
+  where:   { status: "active" },
+  orderBy: { createdAt: "desc" },
+  page:    1,
+  pageSize: 20,
+})
+
+fetch(`/api/products?${qs}`)
+```
+
+## Authentication
+
+Enable by adding an `auth` block to `ApiPlugin`:
+
+```typescript
+const roles = ["admin", "editor", "user"] as const
+type Role = (typeof roles)[number]
+
+new ApiPlugin<Role>({
+  auth: {
+    roles,
+    defaultRole: "user",
+    jwt: {
+      secret:    "your-secret-key-at-least-32-characters",
+      expiresIn: "7d",
+    },
+    session: {
+      store:  "memory",  // or a custom SessionStore instance
+      maxAge: 86400,
+    },
+    defaultPermission: {
+      create: ["admin"],
+      read:   true,
+      update: ["admin", "editor"],
+      delete: ["admin"],
+    },
+  },
+})
+```
+
+JWT and session can be active simultaneously. Responses include both a token and a `sessionId` cookie.
+
+A `user` schema with an `email` field must exist before enabling auth. The plugin creates an `authentication` table automatically.
+
+### Auth endpoints
+
+| Method | Path                  | Description                              |
+| ------ | --------------------- | ---------------------------------------- |
+| `POST` | `/api/auth/register`  | Create a new user account                |
+| `POST` | `/api/auth/login`     | Login — returns token and/or sets cookie |
+| `POST` | `/api/auth/logout`    | Invalidate session                       |
+| `GET`  | `/api/auth/me`        | Get the currently authenticated user     |
+
+Endpoint paths are configurable via `auth.endpoints`. Registration can be disabled with `auth.endpoints.disableRegister: true`.
+
+### Authenticated requests
+
+```http
+GET /api/products
+Authorization: Bearer eyJ...
+```
+
+Or send the `sessionId` cookie — the browser handles this automatically.
+
+### Permissions
+
+Defined per schema in `SchemaDefinition.permission`:
+
+```typescript
+defineSchema({
+  name: "product",
+  fields: { ... },
+  permission: {
+    create: ["admin", "editor"],
+    read:   true,               // public
+    update: ["admin", "editor"],
+    delete: ["admin"],
+  },
+})
+```
+
+Permission values: `true` (public), `false` (blocked), role array, async function, or a mixed array (OR logic). Field-level `read`/`write` permissions are also supported per field.
+
+## File uploads
+
+File upload support is in a separate package to keep `sharp` out of the core dependency tree. See [`@datrix/api-upload`](../api-upload/README.md) for the full setup, storage provider docs, format conversion, and resolution variants.
+
+```typescript
+import { Upload, LocalStorageProvider } from "@datrix/api-upload"
+
+new ApiPlugin({
+  upload: new Upload({
+    provider: new LocalStorageProvider({
+      basePath: "./uploads",
+      baseUrl:  "https://example.com/uploads",
+    }),
+    format:  "webp",
+    quality: 80,
+    resolutions: {
+      thumbnail: { width: 150, height: 150, fit: "cover" },
+      small:     { width: 320 },
+    },
+  }),
+})
+```
+
+## Architecture
+
+```text
+src/
+├── api.ts                   # ApiPlugin class — plugin lifecycle, schema injection, request routing
+├── interface.ts             # IApiPlugin interface — used internally to avoid circular deps
+├── types.ts                 # ApiConfig type
+├── index.ts                 # Public exports
+├── helper/
+│   └── index.ts             # handleRequest, toWebRequest, sendWebResponse, queryToParams
+├── handler/
+│   ├── unified.ts           # CRUD request handler (GET / POST / PATCH / DELETE)
+│   ├── auth-handler.ts      # Auth endpoint handlers (register, login, logout, me)
+│   └── utils.ts             # jsonResponse, datrixErrorResponse helpers
+├── auth/
+│   ├── manager.ts           # AuthManager — coordinates JWT, session, and password
+│   ├── jwt.ts               # JwtStrategy — signing/verification (no external deps)
+│   ├── session.ts           # SessionStrategy + MemorySessionStore
+│   ├── password.ts          # PasswordManager — PBKDF2 hashing
+│   └── types.ts             # AuthConfig, SessionConfig, JwtConfig, SessionData, etc.
+├── middleware/
+│   ├── context.ts           # RequestContext builder
+│   ├── permission.ts        # Schema and field permission evaluation
+│   └── types.ts             # RequestContext type
+└── errors/
+    ├── api-error.ts         # DatrixApiError and handlerError factory
+    └── auth-error.ts        # DatrixAuthError and authError factory
+```

package/dist/index.d.mts

@@ -0,0 +1,305 @@
+import { DefaultPermission, IAuthManager, AuthUser, LoginResult, AuthContext, IUpload, BasePlugin, IApiPlugin, Datrix, QueryContext, PluginContext, SchemaDefinition, DatrixEntry, QueryObject, PermissionAction, ParsedQuery, FallbackInput, ParserError, PermissionValue, PermissionCheckResult, FieldPermissionCheckResult, RawQueryParams, ParserOptions, FallbackWhereClause, PopulateClause, DatrixRecord, DatrixError } from '@datrix/core';
+export { PermissionAction } from '@datrix/core';
+
+interface PasswordHash {
+    readonly hash: string;
+    readonly salt: string;
+}
+interface PasswordConfig {
+    readonly iterations?: number;
+    readonly keyLength?: number;
+    readonly minLength?: number;
+}
+
+interface JwtPayload {
+    readonly userId: number;
+    readonly role: string;
+    readonly iat: number;
+    readonly exp: number;
+    readonly iss?: string;
+    readonly aud?: string;
+    readonly [key: string]: unknown;
+}
+interface SessionStore {
+    get(sessionId: string): Promise<SessionData | undefined>;
+    set(sessionId: string, data: SessionData): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    cleanup(): Promise<number>;
+    clear(): Promise<void>;
+}
+interface SessionData {
+    readonly id: string;
+    readonly userId: number;
+    readonly role: string;
+    readonly createdAt: Date;
+    readonly expiresAt: Date;
+    readonly lastAccessedAt: Date;
+    readonly [key: string]: unknown;
+}
+type JwtAlgorithm = "HS256" | "HS512";
+type TimeUnit = "s" | "m" | "h" | "d";
+type ExpiryString = `${number}${TimeUnit}`;
+interface JwtConfig {
+    readonly secret: string;
+    readonly expiresIn?: ExpiryString | number;
+    readonly algorithm?: JwtAlgorithm;
+    readonly issuer?: string;
+    readonly audience?: string;
+}
+interface SessionConfig {
+    readonly store?: "memory" | SessionStore;
+    readonly maxAge?: number;
+    readonly checkPeriod?: number;
+    readonly prefix?: string;
+}
+interface AuthConfig<TRole extends string = string> {
+    readonly roles: readonly TRole[];
+    readonly defaultRole: TRole;
+    readonly defaultPermission?: DefaultPermission<TRole>;
+    readonly jwt?: JwtConfig;
+    readonly session?: SessionConfig;
+    readonly password?: PasswordConfig;
+    readonly authSchemaName?: string;
+    readonly userSchema?: {
+        readonly name?: string;
+        readonly email?: string;
+    };
+    readonly endpoints?: {
+        readonly login?: string;
+        readonly register?: string;
+        readonly logout?: string;
+        readonly me?: string;
+        readonly disableRegister?: boolean;
+    };
+}
+
+declare class JwtStrategy {
+    private readonly secret;
+    private readonly expiresIn;
+    private readonly algorithm;
+    private readonly issuer;
+    private readonly audience;
+    constructor(config: JwtConfig);
+    sign(payload: Omit<JwtPayload, "iat" | "exp" | "iss" | "aud">): string;
+    verify(token: string): JwtPayload;
+    refresh(token: string): string;
+    decode(token: string): JwtPayload;
+    private createToken;
+    private signData;
+    private encodeBase64Url;
+    private decodeBase64Url;
+    private constantTimeCompare;
+    private parseExpiry;
+}
+
+declare class SessionStrategy {
+    private readonly store;
+    private readonly maxAge;
+    private readonly checkPeriod;
+    private cleanupTimer;
+    constructor(config: SessionConfig);
+    create(userId: number, role: string, data?: Record<string, unknown>): Promise<SessionData>;
+    get(sessionId: string): Promise<SessionData>;
+    update(sessionId: string, data: Partial<Omit<SessionData, "id" | "createdAt">>): Promise<SessionData>;
+    delete(sessionId: string): Promise<void>;
+    refresh(sessionId: string): Promise<SessionData>;
+    validate(sessionId: string): Promise<boolean>;
+    startCleanup(): void;
+    stopCleanup(): void;
+    clear(): Promise<void>;
+    private generateSessionId;
+}
+declare class MemorySessionStore implements SessionStore {
+    readonly name: "memory";
+    private readonly sessions;
+    private readonly prefix;
+    constructor(prefix?: string);
+    get(sessionId: string): Promise<SessionData | undefined>;
+    set(sessionId: string, data: SessionData): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    cleanup(): Promise<number>;
+    clear(): Promise<void>;
+    private getKey;
+}
+
+declare class AuthManager<TRole extends string = string> implements IAuthManager {
+    private readonly passwordManager;
+    private readonly jwtStrategy;
+    private readonly sessionStrategy;
+    private readonly config;
+    get authConfig(): AuthConfig<TRole>;
+    constructor(config: AuthConfig<TRole>);
+    hashPassword(password: string): Promise<PasswordHash>;
+    verifyPassword(password: string, hash: string, salt: string): Promise<boolean>;
+    login(user: AuthUser, options?: {
+        createToken?: boolean;
+        createSession?: boolean;
+    }): Promise<LoginResult>;
+    logout(sessionId: string): Promise<void>;
+    authenticate(request: Request): Promise<AuthContext | null>;
+    private extractToken;
+    private extractSessionId;
+    getJwtStrategy(): JwtStrategy | undefined;
+    getSessionStrategy(): SessionStrategy | undefined;
+    destroy(): Promise<void>;
+}
+
+interface ApiConfig<TRole extends string = string> extends Record<string, unknown> {
+    readonly disabled?: boolean;
+    readonly prefix?: string;
+    readonly defaultPageSize?: number;
+    readonly maxPageSize?: number;
+    readonly maxPopulateDepth?: number;
+    readonly auth?: AuthConfig<TRole>;
+    readonly upload?: IUpload;
+    readonly excludeSchemas?: readonly string[];
+}
+
+declare class ApiPlugin<TRole extends string = string> extends BasePlugin<ApiConfig<TRole>> implements IApiPlugin<TRole> {
+    readonly name = "api";
+    readonly version = "1.0.0";
+    authManager?: AuthManager;
+    user: AuthUser | null;
+    private datrixInstance?;
+    get datrix(): Datrix;
+    get upload(): IUpload | undefined;
+    setUser(user: AuthUser | null): void;
+    private get authConfig();
+    private get apiConfig();
+    private get authSchemaName();
+    private get userSchemaName();
+    private get userSchemaEmailField();
+    get authDefaultPermission(): DefaultPermission<TRole> | undefined;
+    get authDefaultRole(): TRole | undefined;
+    get excludeSchemas(): readonly string[];
+    private getTableName;
+    onCreateQueryContext(context: QueryContext): Promise<QueryContext>;
+    init(context: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+    getSchemas(): Promise<SchemaDefinition[]>;
+    onBeforeQuery<T extends DatrixEntry>(query: QueryObject<T>, context: QueryContext): Promise<QueryObject<T>>;
+    onAfterQuery<TResult>(result: TResult, context: QueryContext): Promise<TResult>;
+    private createAuthenticationRecord;
+    private syncAuthenticationEmail;
+    handleRequest(request: Request, datrix: Datrix): Promise<Response>;
+    private isAuthPath;
+    private handleAuthRequest;
+    isEnabled(): boolean;
+    isAuthEnabled(): boolean;
+    getAuthManager(): AuthManager | undefined;
+}
+
+declare function handleRequest(datrix: Datrix, request: Request): Promise<Response>;
+
+type HttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+interface RequestContext<TRole extends string = string> {
+    readonly schema: SchemaDefinition | null;
+    readonly action: PermissionAction;
+    readonly id: number | null;
+    readonly method: HttpMethod;
+    readonly query: ParsedQuery | null;
+    readonly body: FallbackInput | null;
+    readonly headers: Record<string, string>;
+    readonly url: URL;
+    readonly request: Request;
+    readonly user: AuthUser | null;
+    readonly datrix: Datrix;
+    readonly api: IApiPlugin<TRole>;
+    readonly authEnabled: boolean;
+}
+interface ContextBuilderOptions {
+    readonly apiPrefix?: string;
+}
+
+declare class ContextBuildError extends Error {
+    readonly parserError: ParserError;
+    constructor(parserError: ParserError);
+}
+declare function buildRequestContext<TRole extends string = string>(request: Request, datrix: Datrix, api: IApiPlugin<TRole>, options?: ContextBuilderOptions): Promise<RequestContext<TRole>>;
+
+declare function authenticate(request: Request, authManager?: AuthManager): Promise<AuthUser | null>;
+
+declare function evaluatePermissionValue<TRoles extends string>(value: PermissionValue<TRoles> | undefined, ctx: RequestContext): Promise<boolean>;
+declare function checkSchemaPermission<TRoles extends string>(schema: SchemaDefinition<TRoles>, ctx: RequestContext, defaultPermission?: DefaultPermission<TRoles>): Promise<PermissionCheckResult>;
+declare function filterFieldsForRead<TRoles extends string, TRecord extends DatrixEntry>(schema: SchemaDefinition<TRoles>, record: TRecord, ctx: RequestContext): Promise<{
+    data: Partial<TRecord>;
+    deniedFields: string[];
+}>;
+declare function checkFieldsForWrite<TRoles extends string>(schema: SchemaDefinition<TRoles>, ctx: RequestContext): Promise<FieldPermissionCheckResult>;
+declare function methodToAction(method: string): PermissionAction;
+declare function filterRecordsForRead<TRoles extends string, TRecord extends DatrixEntry>(schema: SchemaDefinition<TRoles>, records: readonly TRecord[], ctx: RequestContext): Promise<Partial<TRecord>[]>;
+
+declare function parseQuery(params: RawQueryParams, options?: Partial<ParserOptions>): ParsedQuery<DatrixEntry>;
+
+declare function parseWhere(params: RawQueryParams): FallbackWhereClause | undefined;
+
+declare function parsePopulate(params: RawQueryParams, maxDepth?: number): PopulateClause<DatrixRecord> | undefined;
+
+declare function parseFields(params: RawQueryParams): string[] | "*" | undefined;
+
+declare function queryToParams<T extends DatrixEntry = DatrixRecord>(query: ParsedQuery<T> | undefined): string;
+declare function serializeQuery<T extends DatrixEntry = DatrixEntry>(query: ParsedQuery<T>): RawQueryParams;
+
+declare function handleCrudRequest<TRole extends string = string>(request: Request, datrix: Datrix, api: IApiPlugin<TRole>, options?: ContextBuilderOptions): Promise<Response>;
+
+interface AuthHandlerConfig {
+    readonly datrix: Datrix;
+    readonly authManager: AuthManager;
+    readonly authConfig: AuthConfig;
+}
+declare function createAuthHandlers(config: AuthHandlerConfig): {
+    register: (request: Request) => Promise<Response>;
+    login: (request: Request) => Promise<Response>;
+    logout: (request: Request) => Promise<Response>;
+    me: (request: Request) => Promise<Response>;
+};
+declare function createUnifiedAuthHandler(config: AuthHandlerConfig, apiPrefix?: string): (request: Request) => Promise<Response>;
+
+declare class DatrixApiError extends DatrixError {
+    status: number;
+    constructor(message: string, options: ApiErrorOptions);
+    toJSON(): {
+        status: number;
+        type: string;
+        message: string;
+        code: string;
+        timestamp: string;
+        operation?: string;
+        context?: Record<string, unknown>;
+        suggestion?: string;
+        expected?: string;
+        received?: unknown;
+        documentation?: string;
+        cause?: {
+            readonly message: string;
+            readonly name: string;
+        };
+    };
+}
+interface ApiErrorOptions {
+    code: string;
+    status: number;
+    operation?: string;
+    context?: Record<string, unknown>;
+    suggestion?: string;
+    expected?: string;
+    received?: unknown;
+    cause?: Error;
+}
+declare const handlerError: {
+    schemaNotFound(tableName: string, availableModels?: string[]): DatrixApiError;
+    modelNotSpecified(): DatrixApiError;
+    recordNotFound(modelName: string, id: number | string): DatrixApiError;
+    invalidBody(reason?: string): DatrixApiError;
+    missingId(operation: string): DatrixApiError;
+    methodNotAllowed(method: string): DatrixApiError;
+    permissionDenied(reason: string, context?: Record<string, unknown>): DatrixApiError;
+    unauthorized(reason?: string): DatrixApiError;
+    internalError(message: string, cause?: Error): DatrixApiError;
+    conflict(reason: string, context?: Record<string, unknown>): DatrixApiError;
+};
+
+declare function jsonResponse(data: unknown, status?: number): Response;
+declare function datrixErrorResponse(error: DatrixApiError | DatrixError): Response;
+
+export { ApiPlugin, type AuthHandlerConfig, ContextBuildError, type ContextBuilderOptions, DatrixApiError, type HttpMethod, MemorySessionStore, type RequestContext, authenticate, buildRequestContext, checkFieldsForWrite, checkSchemaPermission, createAuthHandlers, createUnifiedAuthHandler, datrixErrorResponse, evaluatePermissionValue, filterFieldsForRead, filterRecordsForRead, handleCrudRequest, handleRequest, handlerError, jsonResponse, methodToAction, parseFields, parsePopulate, parseQuery, parseWhere, queryToParams, serializeQuery };