@astralibx/staff-engine 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,262 @@
+import { RequestHandler, Request, Response, Router } from 'express';
+import { Document, Types, Connection, Model } from 'mongoose';
+import { IStaff, IPermissionGroup, LogAdapter, IPermissionGroupCreateInput, IPermissionGroupUpdateInput, StaffAdapters, StaffHooks, IStaffCreateInput, IStaffListFilters, IPaginatedResult, IStaffUpdateInput, StaffEngineConfig } from '@astralibx/staff-types';
+export { DEFAULT_OPTIONS, ResolvedOptions, StaffEngineConfig } from '@astralibx/staff-types';
+import { AlxError } from '@astralibx/core';
+export { sendSuccess } from '@astralibx/core';
+
+interface IStaffDocument extends Omit<IStaff, '_id'>, Document {
+    _id: Types.ObjectId;
+}
+declare function createStaffModel(connection: Connection, prefix?: string): Model<IStaffDocument>;
+
+interface IPermissionGroupDocument extends Omit<IPermissionGroup, '_id'>, Document {
+    _id: Types.ObjectId;
+}
+declare function createPermissionGroupModel(connection: Connection, prefix?: string): Model<IPermissionGroupDocument>;
+
+declare class PermissionCacheService {
+    private StaffModel;
+    private ttlMs;
+    private redis;
+    private keyPrefix;
+    private logger;
+    private tenantId?;
+    private memoryCache;
+    constructor(StaffModel: Model<IStaffDocument>, ttlMs: number, redis: unknown | null, keyPrefix: string, logger: LogAdapter, tenantId?: string | undefined);
+    get(staffId: string): Promise<string[]>;
+    invalidate(staffId: string): Promise<void>;
+    invalidateAll(): Promise<void>;
+    private getMemory;
+    private getRedis;
+    private fetchFromDb;
+}
+
+declare class PermissionService {
+    private PermissionGroup;
+    private permissionCache;
+    private logger;
+    private tenantId?;
+    constructor(PermissionGroup: Model<IPermissionGroupDocument>, permissionCache: PermissionCacheService, logger: LogAdapter, tenantId?: string | undefined);
+    private get tenantFilter();
+    listGroups(): Promise<IPermissionGroupDocument[]>;
+    createGroup(data: IPermissionGroupCreateInput): Promise<IPermissionGroupDocument>;
+    updateGroup(groupId: string, data: IPermissionGroupUpdateInput): Promise<IPermissionGroupDocument>;
+    deleteGroup(groupId: string): Promise<void>;
+    getAllPermissionKeys(): Promise<string[]>;
+}
+
+declare class RateLimiterService {
+    private windowMs;
+    private maxAttempts;
+    private redis;
+    private keyPrefix;
+    private logger;
+    private memoryStore;
+    constructor(windowMs: number, maxAttempts: number, redis: unknown | null, keyPrefix: string, logger: LogAdapter);
+    checkLimit(key: string): Promise<{
+        allowed: boolean;
+        remaining: number;
+        retryAfterMs?: number;
+    }>;
+    recordAttempt(key: string): Promise<void>;
+    reset(key: string): Promise<void>;
+    private checkLimitMemory;
+    private recordAttemptMemory;
+    private checkLimitRedis;
+    private recordAttemptRedis;
+}
+
+interface StaffServiceDeps {
+    Staff: Model<IStaffDocument>;
+    PermissionGroup: Model<IPermissionGroupDocument>;
+    adapters: StaffAdapters;
+    hooks: StaffHooks;
+    permissionCache: PermissionCacheService;
+    rateLimiter: RateLimiterService;
+    logger: LogAdapter;
+    tenantId?: string;
+    jwtSecret: string;
+    staffTokenExpiry: string;
+    ownerTokenExpiry: string;
+    requireEmailUniqueness: boolean;
+    allowSelfPasswordChange: boolean;
+}
+declare class StaffService {
+    private Staff;
+    private PermissionGroup;
+    private adapters;
+    private hooks;
+    private permissionCache;
+    private rateLimiter;
+    private logger;
+    private tenantId?;
+    private jwtSecret;
+    private staffTokenExpiry;
+    private ownerTokenExpiry;
+    private requireEmailUniqueness;
+    private allowSelfPasswordChange;
+    constructor(deps: StaffServiceDeps);
+    private get tenantFilter();
+    private generateToken;
+    setupOwner(data: {
+        name: string;
+        email: string;
+        password: string;
+    }): Promise<{
+        staff: IStaffDocument;
+        token: string;
+    }>;
+    login(email: string, password: string, ip?: string): Promise<{
+        staff: IStaffDocument;
+        token: string;
+    }>;
+    create(data: IStaffCreateInput): Promise<IStaffDocument>;
+    list(filters?: IStaffListFilters): Promise<IPaginatedResult<IStaffDocument>>;
+    getById(staffId: string): Promise<IStaffDocument>;
+    update(staffId: string, data: IStaffUpdateInput): Promise<IStaffDocument>;
+    updatePermissions(staffId: string, permissions: string[]): Promise<IStaffDocument>;
+    updateStatus(staffId: string, status: string): Promise<IStaffDocument>;
+    resetPassword(staffId: string, newPassword: string): Promise<void>;
+    changeOwnPassword(staffId: string, oldPassword: string, newPassword: string): Promise<void>;
+}
+
+interface StaffUser {
+    staffId: string;
+    role: string;
+    permissions: string[];
+}
+interface AuthenticatedRequest extends Request {
+    user: StaffUser;
+}
+interface AuthMiddleware {
+    verifyToken: RequestHandler;
+    resolveStaff: (token: string) => Promise<StaffUser | null>;
+    requirePermission: (...keys: string[]) => RequestHandler;
+    ownerOnly: RequestHandler;
+    requireRole: (...roles: string[]) => RequestHandler;
+}
+declare function createAuthMiddleware(jwtSecret: string, permissionCache: PermissionCacheService, StaffModel: Model<IStaffDocument>, logger: LogAdapter, tenantId?: string): AuthMiddleware;
+
+declare const ERROR_CODE: {
+    readonly InvalidCredentials: "STAFF_INVALID_CREDENTIALS";
+    readonly AccountInactive: "STAFF_ACCOUNT_INACTIVE";
+    readonly AccountPending: "STAFF_ACCOUNT_PENDING";
+    readonly RateLimited: "STAFF_RATE_LIMITED";
+    readonly TokenExpired: "STAFF_TOKEN_EXPIRED";
+    readonly TokenInvalid: "STAFF_TOKEN_INVALID";
+    readonly InsufficientPermissions: "STAFF_INSUFFICIENT_PERMISSIONS";
+    readonly OwnerOnly: "STAFF_OWNER_ONLY";
+    readonly StaffNotFound: "STAFF_NOT_FOUND";
+    readonly EmailExists: "STAFF_EMAIL_EXISTS";
+    readonly SetupAlreadyComplete: "STAFF_SETUP_ALREADY_COMPLETE";
+    readonly LastOwnerGuard: "STAFF_LAST_OWNER_GUARD";
+    readonly InvalidPermissions: "STAFF_INVALID_PERMISSIONS";
+    readonly GroupNotFound: "STAFF_GROUP_NOT_FOUND";
+    readonly GroupIdExists: "STAFF_GROUP_ID_EXISTS";
+    readonly InvalidConfig: "STAFF_INVALID_CONFIG";
+};
+type ErrorCode = (typeof ERROR_CODE)[keyof typeof ERROR_CODE];
+declare const ERROR_MESSAGE: {
+    readonly InvalidCredentials: "Invalid email or password";
+    readonly AccountInactive: "Account is deactivated";
+    readonly AccountPending: "Account is pending activation";
+    readonly RateLimited: "Too many login attempts. Please try again later.";
+    readonly TokenExpired: "Token has expired";
+    readonly TokenInvalid: "Invalid token";
+    readonly InsufficientPermissions: "Insufficient permissions";
+    readonly OwnerOnly: "This action requires owner privileges";
+    readonly StaffNotFound: "Staff member not found";
+    readonly EmailExists: "A staff member with this email already exists";
+    readonly SetupAlreadyComplete: "Initial setup has already been completed";
+    readonly LastOwnerGuard: "Cannot deactivate the last active owner";
+    readonly InvalidPermissions: "Edit permissions require corresponding view permissions";
+    readonly GroupNotFound: "Permission group not found";
+    readonly GroupIdExists: "A permission group with this ID already exists";
+    readonly InvalidConfig: "Invalid engine configuration";
+};
+declare const DEFAULTS: {
+    readonly ListPageSize: 20;
+    readonly MaxListPageSize: 100;
+    readonly PermissionCacheTtlMs: number;
+};
+declare const DEFAULT_AUTH: {
+    readonly staffTokenExpiry: "24h";
+    readonly ownerTokenExpiry: "30d";
+    readonly permissionCacheTtlMs: number;
+};
+
+declare class AlxStaffError extends AlxError {
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+}
+declare class AuthenticationError extends AlxStaffError {
+    constructor(code?: string, message?: string);
+}
+declare class AuthorizationError extends AlxStaffError {
+    constructor(code?: string, message?: string);
+}
+declare class RateLimitError extends AlxStaffError {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
+declare class TokenError extends AlxStaffError {
+    constructor(code?: string, message?: string);
+}
+declare class StaffNotFoundError extends AlxStaffError {
+    readonly staffId: string;
+    constructor(staffId: string);
+}
+declare class DuplicateError extends AlxStaffError {
+    constructor(code: string, message: string, context?: Record<string, unknown>);
+}
+declare class SetupError extends AlxStaffError {
+    constructor();
+}
+declare class LastOwnerError extends AlxStaffError {
+    readonly staffId: string;
+    constructor(staffId: string);
+}
+declare class InvalidPermissionError extends AlxStaffError {
+    readonly missingViewKeys: string[];
+    constructor(missingViewKeys: string[]);
+}
+declare class GroupNotFoundError extends AlxStaffError {
+    readonly groupId: string;
+    constructor(groupId: string);
+}
+declare class InvalidConfigError extends AlxStaffError {
+    readonly field: string;
+    readonly reason: string;
+    constructor(field: string, reason: string);
+}
+
+/**
+ * Validates that for every edit-type permission, the corresponding view-type permission
+ * is also present. Single-level cascade only.
+ * Example: 'chat:edit' requires 'chat:view'
+ */
+declare function validatePermissionPairs(permissions: string[], allGroups: IPermissionGroupDocument[]): void;
+
+declare function handleStaffError(res: Response, error: unknown, logger: LogAdapter): void;
+
+interface RouteServices {
+    staff: StaffService;
+    permissions: PermissionService;
+}
+declare function createRoutes(services: RouteServices, auth: AuthMiddleware, logger: LogAdapter, allowSelfPasswordChange: boolean): Router;
+
+interface StaffEngine {
+    routes: Router;
+    auth: AuthMiddleware;
+    staff: StaffService;
+    permissions: PermissionService;
+    models: {
+        Staff: Model<IStaffDocument>;
+        PermissionGroup: Model<IPermissionGroupDocument>;
+    };
+    destroy: () => Promise<void>;
+}
+declare function createStaffEngine(config: StaffEngineConfig): StaffEngine;
+
+export { AlxStaffError, type AuthMiddleware, type AuthenticatedRequest, AuthenticationError, AuthorizationError, DEFAULTS, DEFAULT_AUTH, DuplicateError, ERROR_CODE, ERROR_MESSAGE, type ErrorCode, GroupNotFoundError, type IPermissionGroupDocument, type IStaffDocument, InvalidConfigError, InvalidPermissionError, LastOwnerError, PermissionCacheService, PermissionService, RateLimitError, RateLimiterService, SetupError, type StaffEngine, StaffNotFoundError, StaffService, type StaffUser, TokenError, createAuthMiddleware, createPermissionGroupModel, createRoutes, createStaffEngine, createStaffModel, handleStaffError, validatePermissionPairs };