@technomoron/api-server-base 1.1.5 → 1.1.7

package/dist/cjs/api-server-base.cjs

@@ -325,7 +325,7 @@ function fillConfig(config) {
         accessCookie: config.accessCookie ?? 'dat',
         refreshCookie: config.refreshCookie ?? 'drt',
         accessExpiry: config.accessExpiry ?? 60 * 15,
-        refreshExpiry: config.refreshExpiry ?? 30 * 24 * 60 * 60 * 1000,
+        refreshExpiry: config.refreshExpiry ?? 30 * 24 * 60 * 60,
         authApi: config.authApi ?? false,
         devMode: config.devMode ?? false,
         hydrateGetBody: config.hydrateGetBody ?? true,
@@ -335,7 +335,9 @@ function fillConfig(config) {
 class ApiServer {
     constructor(config = {}) {
         this.currReq = null;
+        this.apiNotFoundHandler = null;
         this.config = fillConfig(config);
+        this.apiBasePath = this.normalizeApiBasePath(this.config.apiBasePath);
         this.storageAdapter = auth_storage_js_1.nullAuthStorage;
         this.moduleAdapter = auth_module_js_1.nullAuthModule;
         this.app = (0, express_1.default)();
@@ -345,6 +347,7 @@ class ApiServer {
         }
         this.middlewares();
         // addSwaggerUi(this.app);
+        this.installApiNotFoundHandler();
     }
     authStorage(storage) {
         this.storageAdapter = storage;
@@ -493,6 +496,56 @@ class ApiServer {
         };
         this.app.use((0, cors_1.default)(corsOptions));
     }
+    normalizeApiBasePath(path) {
+        if (!path || typeof path !== 'string') {
+            return '/api';
+        }
+        const trimmed = path.trim();
+        if (!trimmed) {
+            return '/api';
+        }
+        const withLeadingSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+        if (withLeadingSlash.length === 1) {
+            return withLeadingSlash;
+        }
+        return withLeadingSlash.replace(/\/+$/, '') || '/api';
+    }
+    installApiNotFoundHandler() {
+        if (this.apiNotFoundHandler) {
+            return;
+        }
+        this.apiNotFoundHandler = (req, res) => {
+            const payload = {
+                code: 404,
+                message: this.describeMissingEndpoint(req),
+                data: null,
+                errors: {}
+            };
+            res.status(404).json(payload);
+        };
+        this.app.use(this.apiBasePath, this.apiNotFoundHandler);
+    }
+    ensureApiNotFoundOrdering() {
+        this.installApiNotFoundHandler();
+        if (!this.apiNotFoundHandler) {
+            return;
+        }
+        const stack = this.app?._router?.stack;
+        if (!stack) {
+            return;
+        }
+        const index = stack.findIndex((layer) => layer.handle === this.apiNotFoundHandler);
+        if (index === -1 || index === stack.length - 1) {
+            return;
+        }
+        const [layer] = stack.splice(index, 1);
+        stack.push(layer);
+    }
+    describeMissingEndpoint(req) {
+        const method = typeof req.method === 'string' ? req.method.toUpperCase() : 'GET';
+        const target = req.originalUrl || req.url || this.apiBasePath;
+        return `No such endpoint: ${method} ${target}`;
+    }
     start() {
         this.app
             .listen({
@@ -628,18 +681,18 @@ class ApiServer {
     handle_request(handler, auth) {
         return async (req, res, next) => {
             void next;
+            const apiReq = {
+                server: this,
+                req,
+                res,
+                token: '',
+                tokenData: null,
+                getClientInfo: () => ensureClientInfo(apiReq),
+                getClientIp: () => ensureClientInfo(apiReq).ip,
+                getClientIpChain: () => ensureClientInfo(apiReq).ipchain
+            };
+            this.currReq = apiReq;
             try {
-                const apiReq = {
-                    server: this,
-                    req,
-                    res,
-                    token: '',
-                    tokenData: null,
-                    getClientInfo: () => ensureClientInfo(apiReq),
-                    getClientIp: () => ensureClientInfo(apiReq).ip,
-                    getClientIpChain: () => ensureClientInfo(apiReq).ipchain
-                };
-                this.currReq = apiReq;
                 if (this.config.hydrateGetBody) {
                     hydrateGetBody(apiReq.req);
                 }
@@ -660,7 +713,11 @@ class ApiServer {
                     throw new ApiError({ code: 500, message: 'Handler result must start with a numeric status code' });
                 }
                 const message = typeof rawMessage === 'string' ? rawMessage : 'Success';
-                res.status(code).json({ code, message, data });
+                const responsePayload = { code, message, data };
+                if (this.config.debug) {
+                    this.dumpResponse(apiReq, responsePayload, code);
+                }
+                res.status(code).json(responsePayload);
             }
             catch (error) {
                 if (error instanceof ApiError || isApiErrorLike(error)) {
@@ -668,20 +725,28 @@ class ApiServer {
                     const normalizedErrors = apiError.errors && typeof apiError.errors === 'object' && !Array.isArray(apiError.errors)
                         ? apiError.errors
                         : {};
-                    res.status(apiError.code).json({
+                    const errorPayload = {
                         code: apiError.code,
                         message: apiError.message,
                         data: apiError.data ?? null,
                         errors: normalizedErrors
-                    });
+                    };
+                    if (this.config.debug) {
+                        this.dumpResponse(apiReq, errorPayload, apiError.code);
+                    }
+                    res.status(apiError.code).json(errorPayload);
                 }
                 else {
-                    res.status(500).json({
+                    const errorPayload = {
                         code: 500,
                         message: this.guessExceptionText(error),
                         data: null,
                         errors: {}
-                    });
+                    };
+                    if (this.config.debug) {
+                        this.dumpResponse(apiReq, errorPayload, 500);
+                    }
+                    res.status(500).json(errorPayload);
                 }
             }
         };
@@ -693,7 +758,7 @@ class ApiServer {
             this.authModule(module);
         }
         module.checkConfig();
-        const base = this.config.apiBasePath ?? '/api';
+        const base = this.apiBasePath;
         const ns = module.namespace;
         const mountPath = `${base}${ns}`;
         module.mountpath = mountPath;
@@ -705,6 +770,7 @@ class ApiServer {
             }
         });
         this.app.use(mountPath, router);
+        this.ensureApiNotFoundOrdering();
         return this;
     }
     dumpRequest(apiReq) {
@@ -719,6 +785,59 @@ class ApiServer {
         console.log('Headers:', req.headers);
         console.log('------------------------');
     }
+    formatDebugValue(value, maxLength = 50, seen = new WeakSet()) {
+        if (value === null || value === undefined) {
+            return value;
+        }
+        if (typeof value === 'string') {
+            return value.length <= maxLength
+                ? value
+                : `${value.slice(0, maxLength)}… [truncated ${value.length - maxLength} chars]`;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+            return value;
+        }
+        if (typeof value === 'symbol') {
+            return value.toString();
+        }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) {
+            return `<Buffer length=${value.length}>`;
+        }
+        if (typeof value === 'function') {
+            return `[Function ${value.name || 'anonymous'}]`;
+        }
+        if (typeof value === 'object') {
+            const obj = value;
+            if (seen.has(obj)) {
+                return '[Circular]';
+            }
+            seen.add(obj);
+            if (Array.isArray(value)) {
+                const arr = value.map((item) => this.formatDebugValue(item, maxLength, seen));
+                seen.delete(obj);
+                return arr;
+            }
+            const recordValue = value;
+            const entries = Object.entries(recordValue).reduce((acc, [key, val]) => {
+                acc[key] = this.formatDebugValue(val, maxLength, seen);
+                return acc;
+            }, {});
+            seen.delete(obj);
+            return entries;
+        }
+        return value;
+    }
+    dumpResponse(apiReq, payload, status) {
+        const url = apiReq.req.originalUrl || apiReq.req.url;
+        console.log('--- Outgoing Response! ---');
+        console.log('URL:', url);
+        console.log('Status:', status);
+        console.log('Payload:', this.formatDebugValue(payload));
+        console.log('--------------------------');
+    }
 }
 exports.ApiServer = ApiServer;
 exports.default = ApiServer;

package/dist/cjs/api-server-base.d.ts

@@ -9,7 +9,7 @@ import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
 import { ApiModule } from './api-module.js';
 import type { ApiAuthClass, ApiKey } from './api-module.js';
 import type { AuthProviderModule } from './auth-module.js';
-import type { AuthStorage, AuthTokenData } from './auth-storage.js';
+import type { AuthStorage, AuthTokenData, AuthTokenMetadata } from './auth-storage.js';
 export type { Application, Request, Response, NextFunction, Router } from 'express';
 export type { Multer } from 'multer';
 export type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
@@ -35,7 +35,7 @@ interface JwtDecodeResult<T> {
     data?: T;
     error?: string;
 }
-export interface ApiTokenData extends JwtPayload {
+export interface ApiTokenData extends JwtPayload, AuthTokenMetadata {
     uid: unknown;
     iat?: number;
     exp?: number;
@@ -101,8 +101,10 @@ export declare class ApiServer {
     app: Application;
     currReq: ApiRequest | null;
     readonly config: ApiServerConf;
+    private readonly apiBasePath;
     private storageAdapter;
     private moduleAdapter;
+    private apiNotFoundHandler;
     constructor(config?: Partial<ApiServerConf>);
     authStorage<UserRow, SafeUser>(storage: AuthStorage<UserRow, SafeUser>): this;
     /**
@@ -134,6 +136,10 @@ export declare class ApiServer {
     guessExceptionText(error: any, defMsg?: string): string;
     protected authorize(apiReq: ApiRequest, requiredClass: ApiAuthClass): Promise<void>;
     private middlewares;
+    private normalizeApiBasePath;
+    private installApiNotFoundHandler;
+    private ensureApiNotFoundOrdering;
+    private describeMissingEndpoint;
     start(): this;
     private verifyJWT;
     private authenticate;
@@ -144,5 +150,7 @@ export declare class ApiServer {
     private handle_request;
     api<T extends ApiModule<any>>(module: T): this;
     dumpRequest(apiReq: ApiRequest): void;
+    private formatDebugValue;
+    dumpResponse(apiReq: ApiRequest, payload: unknown, status: number): void;
 }
 export default ApiServer;

package/dist/cjs/auth-storage.d.ts

@@ -9,6 +9,7 @@ export interface AuthTokenMetadata {
     ip?: string;
     os?: string;
     scope?: string | string[];
+    loginType?: string;
     revokeSessions?: 'device' | 'domain' | 'client' | 'user';
 }
 export interface AuthTokenData extends AuthTokenMetadata {

package/dist/esm/api-server-base.d.ts

@@ -9,7 +9,7 @@ import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
 import { ApiModule } from './api-module.js';
 import type { ApiAuthClass, ApiKey } from './api-module.js';
 import type { AuthProviderModule } from './auth-module.js';
-import type { AuthStorage, AuthTokenData } from './auth-storage.js';
+import type { AuthStorage, AuthTokenData, AuthTokenMetadata } from './auth-storage.js';
 export type { Application, Request, Response, NextFunction, Router } from 'express';
 export type { Multer } from 'multer';
 export type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
@@ -35,7 +35,7 @@ interface JwtDecodeResult<T> {
     data?: T;
     error?: string;
 }
-export interface ApiTokenData extends JwtPayload {
+export interface ApiTokenData extends JwtPayload, AuthTokenMetadata {
     uid: unknown;
     iat?: number;
     exp?: number;
@@ -101,8 +101,10 @@ export declare class ApiServer {
     app: Application;
     currReq: ApiRequest | null;
     readonly config: ApiServerConf;
+    private readonly apiBasePath;
     private storageAdapter;
     private moduleAdapter;
+    private apiNotFoundHandler;
     constructor(config?: Partial<ApiServerConf>);
     authStorage<UserRow, SafeUser>(storage: AuthStorage<UserRow, SafeUser>): this;
     /**
@@ -134,6 +136,10 @@ export declare class ApiServer {
     guessExceptionText(error: any, defMsg?: string): string;
     protected authorize(apiReq: ApiRequest, requiredClass: ApiAuthClass): Promise<void>;
     private middlewares;
+    private normalizeApiBasePath;
+    private installApiNotFoundHandler;
+    private ensureApiNotFoundOrdering;
+    private describeMissingEndpoint;
     start(): this;
     private verifyJWT;
     private authenticate;
@@ -144,5 +150,7 @@ export declare class ApiServer {
     private handle_request;
     api<T extends ApiModule<any>>(module: T): this;
     dumpRequest(apiReq: ApiRequest): void;
+    private formatDebugValue;
+    dumpResponse(apiReq: ApiRequest, payload: unknown, status: number): void;
 }
 export default ApiServer;

package/dist/esm/api-server-base.js

@@ -317,7 +317,7 @@ function fillConfig(config) {
         accessCookie: config.accessCookie ?? 'dat',
         refreshCookie: config.refreshCookie ?? 'drt',
         accessExpiry: config.accessExpiry ?? 60 * 15,
-        refreshExpiry: config.refreshExpiry ?? 30 * 24 * 60 * 60 * 1000,
+        refreshExpiry: config.refreshExpiry ?? 30 * 24 * 60 * 60,
         authApi: config.authApi ?? false,
         devMode: config.devMode ?? false,
         hydrateGetBody: config.hydrateGetBody ?? true,
@@ -327,7 +327,9 @@ function fillConfig(config) {
 export class ApiServer {
     constructor(config = {}) {
         this.currReq = null;
+        this.apiNotFoundHandler = null;
         this.config = fillConfig(config);
+        this.apiBasePath = this.normalizeApiBasePath(this.config.apiBasePath);
         this.storageAdapter = nullAuthStorage;
         this.moduleAdapter = nullAuthModule;
         this.app = express();
@@ -337,6 +339,7 @@ export class ApiServer {
         }
         this.middlewares();
         // addSwaggerUi(this.app);
+        this.installApiNotFoundHandler();
     }
     authStorage(storage) {
         this.storageAdapter = storage;
@@ -485,6 +488,56 @@ export class ApiServer {
         };
         this.app.use(cors(corsOptions));
     }
+    normalizeApiBasePath(path) {
+        if (!path || typeof path !== 'string') {
+            return '/api';
+        }
+        const trimmed = path.trim();
+        if (!trimmed) {
+            return '/api';
+        }
+        const withLeadingSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+        if (withLeadingSlash.length === 1) {
+            return withLeadingSlash;
+        }
+        return withLeadingSlash.replace(/\/+$/, '') || '/api';
+    }
+    installApiNotFoundHandler() {
+        if (this.apiNotFoundHandler) {
+            return;
+        }
+        this.apiNotFoundHandler = (req, res) => {
+            const payload = {
+                code: 404,
+                message: this.describeMissingEndpoint(req),
+                data: null,
+                errors: {}
+            };
+            res.status(404).json(payload);
+        };
+        this.app.use(this.apiBasePath, this.apiNotFoundHandler);
+    }
+    ensureApiNotFoundOrdering() {
+        this.installApiNotFoundHandler();
+        if (!this.apiNotFoundHandler) {
+            return;
+        }
+        const stack = this.app?._router?.stack;
+        if (!stack) {
+            return;
+        }
+        const index = stack.findIndex((layer) => layer.handle === this.apiNotFoundHandler);
+        if (index === -1 || index === stack.length - 1) {
+            return;
+        }
+        const [layer] = stack.splice(index, 1);
+        stack.push(layer);
+    }
+    describeMissingEndpoint(req) {
+        const method = typeof req.method === 'string' ? req.method.toUpperCase() : 'GET';
+        const target = req.originalUrl || req.url || this.apiBasePath;
+        return `No such endpoint: ${method} ${target}`;
+    }
     start() {
         this.app
             .listen({
@@ -620,18 +673,18 @@ export class ApiServer {
     handle_request(handler, auth) {
         return async (req, res, next) => {
             void next;
+            const apiReq = {
+                server: this,
+                req,
+                res,
+                token: '',
+                tokenData: null,
+                getClientInfo: () => ensureClientInfo(apiReq),
+                getClientIp: () => ensureClientInfo(apiReq).ip,
+                getClientIpChain: () => ensureClientInfo(apiReq).ipchain
+            };
+            this.currReq = apiReq;
             try {
-                const apiReq = {
-                    server: this,
-                    req,
-                    res,
-                    token: '',
-                    tokenData: null,
-                    getClientInfo: () => ensureClientInfo(apiReq),
-                    getClientIp: () => ensureClientInfo(apiReq).ip,
-                    getClientIpChain: () => ensureClientInfo(apiReq).ipchain
-                };
-                this.currReq = apiReq;
                 if (this.config.hydrateGetBody) {
                     hydrateGetBody(apiReq.req);
                 }
@@ -652,7 +705,11 @@ export class ApiServer {
                     throw new ApiError({ code: 500, message: 'Handler result must start with a numeric status code' });
                 }
                 const message = typeof rawMessage === 'string' ? rawMessage : 'Success';
-                res.status(code).json({ code, message, data });
+                const responsePayload = { code, message, data };
+                if (this.config.debug) {
+                    this.dumpResponse(apiReq, responsePayload, code);
+                }
+                res.status(code).json(responsePayload);
             }
             catch (error) {
                 if (error instanceof ApiError || isApiErrorLike(error)) {
@@ -660,20 +717,28 @@ export class ApiServer {
                     const normalizedErrors = apiError.errors && typeof apiError.errors === 'object' && !Array.isArray(apiError.errors)
                         ? apiError.errors
                         : {};
-                    res.status(apiError.code).json({
+                    const errorPayload = {
                         code: apiError.code,
                         message: apiError.message,
                         data: apiError.data ?? null,
                         errors: normalizedErrors
-                    });
+                    };
+                    if (this.config.debug) {
+                        this.dumpResponse(apiReq, errorPayload, apiError.code);
+                    }
+                    res.status(apiError.code).json(errorPayload);
                 }
                 else {
-                    res.status(500).json({
+                    const errorPayload = {
                         code: 500,
                         message: this.guessExceptionText(error),
                         data: null,
                         errors: {}
-                    });
+                    };
+                    if (this.config.debug) {
+                        this.dumpResponse(apiReq, errorPayload, 500);
+                    }
+                    res.status(500).json(errorPayload);
                 }
             }
         };
@@ -685,7 +750,7 @@ export class ApiServer {
             this.authModule(module);
         }
         module.checkConfig();
-        const base = this.config.apiBasePath ?? '/api';
+        const base = this.apiBasePath;
         const ns = module.namespace;
         const mountPath = `${base}${ns}`;
         module.mountpath = mountPath;
@@ -697,6 +762,7 @@ export class ApiServer {
             }
         });
         this.app.use(mountPath, router);
+        this.ensureApiNotFoundOrdering();
         return this;
     }
     dumpRequest(apiReq) {
@@ -711,5 +777,58 @@ export class ApiServer {
         console.log('Headers:', req.headers);
         console.log('------------------------');
     }
+    formatDebugValue(value, maxLength = 50, seen = new WeakSet()) {
+        if (value === null || value === undefined) {
+            return value;
+        }
+        if (typeof value === 'string') {
+            return value.length <= maxLength
+                ? value
+                : `${value.slice(0, maxLength)}… [truncated ${value.length - maxLength} chars]`;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+            return value;
+        }
+        if (typeof value === 'symbol') {
+            return value.toString();
+        }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) {
+            return `<Buffer length=${value.length}>`;
+        }
+        if (typeof value === 'function') {
+            return `[Function ${value.name || 'anonymous'}]`;
+        }
+        if (typeof value === 'object') {
+            const obj = value;
+            if (seen.has(obj)) {
+                return '[Circular]';
+            }
+            seen.add(obj);
+            if (Array.isArray(value)) {
+                const arr = value.map((item) => this.formatDebugValue(item, maxLength, seen));
+                seen.delete(obj);
+                return arr;
+            }
+            const recordValue = value;
+            const entries = Object.entries(recordValue).reduce((acc, [key, val]) => {
+                acc[key] = this.formatDebugValue(val, maxLength, seen);
+                return acc;
+            }, {});
+            seen.delete(obj);
+            return entries;
+        }
+        return value;
+    }
+    dumpResponse(apiReq, payload, status) {
+        const url = apiReq.req.originalUrl || apiReq.req.url;
+        console.log('--- Outgoing Response! ---');
+        console.log('URL:', url);
+        console.log('Status:', status);
+        console.log('Payload:', this.formatDebugValue(payload));
+        console.log('--------------------------');
+    }
 }
 export default ApiServer;

package/dist/esm/auth-storage.d.ts

@@ -9,6 +9,7 @@ export interface AuthTokenMetadata {
     ip?: string;
     os?: string;
     scope?: string | string[];
+    loginType?: string;
     revokeSessions?: 'device' | 'domain' | 'client' | 'user';
 }
 export interface AuthTokenData extends AuthTokenMetadata {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@technomoron/api-server-base",
-	"version": "1.1.5",
+	"version": "1.1.7",
 	"description": "Api Server Skeleton / Base Class",
 	"type": "module",
 	"main": "./dist/cjs/index.cjs",