@datrix/api 0.1.0

package/dist/index.d.ts

@@ -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 };