@flusys/nestjs-shared 9.1.0 → 9.1.2

package/guards/permission.guard.d.ts

@@ -7,5 +7,4 @@ export declare class PermissionGuard implements CanActivate {
     constructor(reflector: Reflector, permissionCacheService?: SharedPermissionCacheService | undefined);
     canActivate(context: ExecutionContext): Promise<boolean>;
     private normalizeToLogicNode;
-    private evaluateLogicNode;
 }

package/interfaces/branch-hierarchy-resolver.interface.d.ts

@@ -0,0 +1,10 @@
+import { type IBranchHierarchyOptions } from '../utils/branch-hierarchy.util.js';
+export declare const BRANCH_HIERARCHY_RESOLVER = "BRANCH_HIERARCHY_RESOLVER";
+export interface IBranchHierarchyResolver {
+    getDescendantIds(branchIds: string | string[], options?: IBranchHierarchyOptions): Promise<string[]>;
+    getAncestorIds(branchId: string, options?: IBranchHierarchyOptions): Promise<string[]>;
+    isWithinBranch(branchId: string, ancestorId: string): Promise<boolean>;
+    getGrantedBranchIds(userId: string, companyId?: string): Promise<string[]>;
+    getGrantedDescendantIds(userId: string, branchIds: string | string[], options?: IBranchHierarchyOptions): Promise<string[]>;
+    hasBranchAccess(userId: string, branchId: string): Promise<boolean>;
+}

package/interfaces/company-access-resolver.interface.d.ts

@@ -0,0 +1,19 @@
+export declare const COMPANY_ACCESS_RESOLVER = "COMPANY_ACCESS_RESOLVER";
+export interface IAccessibleCompany {
+    id: string;
+    name: string;
+}
+export interface IAccessibleBranch {
+    id: string;
+    companyId: string;
+    parentId: string | null;
+    name: string;
+}
+export interface IUserCompanyAccess {
+    companies: IAccessibleCompany[];
+    branches: IAccessibleBranch[];
+}
+export interface ICompanyAccessResolver {
+    getUserAccess(userId: string): Promise<IUserCompanyAccess>;
+    getCompanyMembers(companyId: string, branchIds?: string[]): Promise<string[]>;
+}

package/interfaces/email-adapter.interface.d.ts

@@ -0,0 +1,27 @@
+import { type ILoggedUserInfo } from './logged-user-info.interface.js';
+export declare const EMAIL_ADAPTER = "EMAIL_ADAPTER";
+export interface IEmailAdapterRecipients {
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    replyTo?: string;
+    emailConfigId?: string;
+}
+export interface IEmailAdapterContent extends IEmailAdapterRecipients {
+    subject: string;
+    html?: string;
+    text?: string;
+}
+export interface IEmailAdapterTemplate extends IEmailAdapterRecipients {
+    templateSlug: string;
+    variables?: Record<string, unknown>;
+}
+export interface IEmailAdapterResult {
+    success: boolean;
+    messageId?: string;
+    error?: string;
+}
+export interface IEmailAdapter {
+    send(options: IEmailAdapterContent, user: ILoggedUserInfo | null): Promise<IEmailAdapterResult>;
+    sendTemplate(options: IEmailAdapterTemplate, user: ILoggedUserInfo | null): Promise<IEmailAdapterResult>;
+}

package/interfaces/expression.interface.d.ts

@@ -0,0 +1,45 @@
+export declare const EXPRESSION_ARITHMETIC_OPS: readonly ["sum", "subtract", "multiply", "divide", "modulo", "power", "average", "min", "max"];
+export type ExpressionArithmeticOp = (typeof EXPRESSION_ARITHMETIC_OPS)[number];
+export declare const EXPRESSION_COMPARISONS: readonly ["equals", "not_equals", "greater_than", "less_than", "greater_or_equal", "less_or_equal", "contains", "not_contains", "starts_with", "ends_with", "in", "not_in", "is_empty", "is_not_empty", "is_true", "is_false", "matches", "not_matches"];
+export type ExpressionComparison = (typeof EXPRESSION_COMPARISONS)[number];
+export declare const UNARY_EXPRESSION_COMPARISONS: readonly ExpressionComparison[];
+export declare const EXPRESSION_DURATION_UNITS: readonly ["second", "minute", "hour", "day", "week", "month", "year"];
+export type ExpressionDurationUnit = (typeof EXPRESSION_DURATION_UNITS)[number];
+export declare const EXPRESSION_DATE_PARTS: readonly ["year", "month", "day", "weekday", "hour", "minute"];
+export type ExpressionDatePart = (typeof EXPRESSION_DATE_PARTS)[number];
+export interface IExpressionCondition {
+    left: Expression;
+    comparison: ExpressionComparison;
+    right?: Expression;
+}
+export interface IExpressionConditionGroup {
+    operator: 'AND' | 'OR';
+    conditions: Array<IExpressionCondition | IExpressionConditionGroup>;
+}
+export type Expression = {
+    type: 'literal';
+    value: string | number | boolean | null;
+} | {
+    type: 'field_ref';
+    ref: string;
+} | {
+    type: 'arithmetic';
+    op: ExpressionArithmeticOp;
+    operands: Expression[];
+} | {
+    type: 'concat';
+    parts: Expression[];
+    separator?: string;
+} | {
+    type: 'template';
+    template: string;
+} | {
+    type: 'function';
+    name: string;
+    args: Expression[];
+} | {
+    type: 'if';
+    condition: IExpressionConditionGroup;
+    whenTrue: Expression;
+    whenFalse?: Expression;
+};

package/interfaces/index.d.ts

@@ -1,8 +1,12 @@
 export * from './ai-assistant-adapter.interface.js';
 export * from './api.interface.js';
+export * from './branch-hierarchy-resolver.interface.js';
+export * from './company-access-resolver.interface.js';
 export * from './datasource.interface.js';
+export * from './email-adapter.interface.js';
 export * from './event-bus.interface.js';
 export * from './event-manager-adapter.interface.js';
+export * from './expression.interface.js';
 export * from './identity.interface.js';
 export * from './logged-user-info.interface.js';
 export * from './message-ref.interface.js';

package/modules/shared-permission-cache/shared-permission-cache.service.d.ts

@@ -1,5 +1,5 @@
 import { HybridCache } from '../../classes/hybrid-cache.class.js';
-import type { PermissionGuardConfig } from '../../interfaces/index.js';
+import type { ILogicNode, PermissionGuardConfig } from '../../interfaces/index.js';
 import { type PermissionCacheKeyOptions } from '../../utils/permission-cache-key.util.js';
 export declare class SharedPermissionCacheService {
     private readonly cache?;
@@ -14,6 +14,11 @@ export declare class SharedPermissionCacheService {
         companyId?: string | null;
         branchId?: string | null;
     } | null | undefined, requiredPermission: string): Promise<void>;
+    assertPermissionLogic(user: {
+        id?: string | null;
+        companyId?: string | null;
+        branchId?: string | null;
+    } | null | undefined, logic: ILogicNode): Promise<void>;
     isCacheConfigured(): boolean;
     matchPermission(userPermissions: string[], requiredPermission: string): boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-shared",
-  "version": "9.1.0",
+  "version": "9.1.2",
   "description": "Common shared utilities for Flusys NestJS applications",
   "type": "module",
   "main": "./fesm/index.js",
@@ -95,7 +95,7 @@
     "class-transformer": "^0.5.1",
     "class-validator": "^0.15.0",
     "keyv": "^5.0.0",
-    "typeorm": "^0.3.0",
+    "typeorm": "^0.3.31",
     "typeorm-naming-strategies": "^4.1.0",
     "winston": "^3.0.0",
     "winston-transport": "^4.9.0",
@@ -104,6 +104,7 @@
     "rxjs": "^7.8.0"
   },
   "dependencies": {
-    "@flusys/nestjs-core": "9.1.0"
+    "@flusys/nestjs-core": "9.1.2",
+    "re2js": "^2.8.6"
   }
 }

package/utils/branch-hierarchy.util.d.ts

@@ -0,0 +1,15 @@
+export interface IBranchHierarchyNode {
+    id: string;
+    parentId?: string | null;
+}
+export interface IBranchHierarchyOptions {
+    includeSelf?: boolean;
+    maxDepth?: number;
+}
+type IdInput = string | null | undefined | ReadonlyArray<string | null | undefined>;
+export declare function normalizeBranchIds(ids: IdInput): string[];
+export declare function collectBranchDescendantIds(nodes: readonly IBranchHierarchyNode[], rootIds: IdInput, { includeSelf, maxDepth }?: IBranchHierarchyOptions): string[];
+export declare function collectBranchAncestorIds(nodes: readonly IBranchHierarchyNode[], branchId: string | null | undefined, { includeSelf, maxDepth }?: IBranchHierarchyOptions): string[];
+export declare function isBranchWithin(nodes: readonly IBranchHierarchyNode[], branchId: string | null | undefined, ancestorId: string | null | undefined): boolean;
+export declare function getBranchPath<T extends IBranchHierarchyNode>(nodes: readonly T[], branchId: string | null | undefined): T[];
+export {};

package/utils/expression.util.d.ts

@@ -0,0 +1,35 @@
+import { type Expression, type IExpressionConditionGroup } from '../interfaces/expression.interface.js';
+export declare const EXPRESSION_LIMITS: {
+    readonly MAX_DEPTH: 16;
+    readonly MAX_NODES: 500;
+    readonly MAX_TEMPLATE_LENGTH: 4000;
+    readonly MAX_TEXT_LENGTH: 100000;
+    readonly MAX_PAD_LENGTH: 1000;
+};
+export type ExpressionErrorCode = 'invalid_node' | 'unknown_function' | 'wrong_arg_count' | 'unknown_comparison' | 'unknown_ref' | 'too_deep' | 'too_many_nodes' | 'template_too_long' | 'text_too_long' | 'expected_number' | 'expected_date' | 'division_by_zero' | 'invalid_unit' | 'invalid_date_part' | 'regex_too_long' | 'regex_invalid' | 'regex_too_complex' | 'regex_input_too_long';
+export declare class ExpressionError extends Error {
+    readonly code: ExpressionErrorCode;
+    readonly variables: Record<string, string | number>;
+    constructor(code: ExpressionErrorCode, variables?: Record<string, string | number>);
+}
+export declare function isExpressionError(error: unknown): error is ExpressionError;
+export interface IExpressionFunction {
+    minArgs: number;
+    maxArgs?: number;
+    regexArgs?: readonly number[];
+    call(args: unknown[], ctx: IExpressionContext): unknown;
+}
+export interface IExpressionContext {
+    resolveRef(ref: string): unknown;
+    now?: () => Date;
+}
+export interface IExpressionValidationOptions {
+    isKnownRef?: (ref: string) => boolean;
+}
+export declare function expressionToText(value: unknown): string | null;
+export declare function expressionToNumber(value: unknown): number | null;
+export declare const EXPRESSION_FUNCTIONS: Readonly<Record<string, IExpressionFunction>>;
+export declare function evaluateExpression(expression: Expression, ctx: IExpressionContext): unknown;
+export declare function evaluateConditionGroup(group: IExpressionConditionGroup, ctx: IExpressionContext): boolean;
+export declare function assertValidExpression(expression: unknown, options?: IExpressionValidationOptions): void;
+export declare function assertValidConditionGroup(group: unknown, options?: IExpressionValidationOptions): void;

package/utils/index.d.ts

@@ -1,6 +1,8 @@
+export * from './branch-hierarchy.util.js';
 export * from './cache-tenant.util.js';
 export * from './date-time.util.js';
 export * from './event-pattern.util.js';
+export * from './expression.util.js';
 export * from './html-sanitizer.util.js';
 export * from './message-ref.util.js';
 export * from './optional-module.util.js';
@@ -8,5 +10,6 @@ export * from './permission-cache-key.util.js';
 export * from './permission-match.util.js';
 export * from './query-helpers.util.js';
 export * from './request.util.js';
+export * from './safe-regex.util.js';
 export * from './string.util.js';
 export * from './token.util.js';

package/utils/permission-match.util.d.ts

@@ -1 +1,19 @@
+import { type IPermissionResolver, type IPermissionScope } from '../interfaces/permission-resolver.interface.js';
+import { type ILogicNode } from '../interfaces/permission.interface.js';
+import { type SharedPermissionCacheService } from '../modules/shared-permission-cache/shared-permission-cache.service.js';
 export declare function matchesPermission(granted: readonly string[], required: string): boolean;
+export interface IPermissionLogicResult {
+    passed: boolean;
+    missingPermissions: string[];
+    operator: 'AND' | 'OR';
+}
+export declare function evaluatePermissionLogic(node: ILogicNode, granted: readonly string[]): IPermissionLogicResult;
+export declare function permissionLogicCodes(node: ILogicNode): string[];
+export declare const MAX_PERMISSION_LOGIC_DEPTH = 5;
+export declare const MAX_PERMISSION_LOGIC_CODES = 50;
+export declare function permissionLogicProblem(value: unknown): 'invalid' | 'empty' | 'too_many' | null;
+export interface IPermissionSources {
+    resolver?: IPermissionResolver;
+    cache?: SharedPermissionCacheService;
+}
+export declare function loadPermissionCodes(scope: IPermissionScope, sources: IPermissionSources): Promise<string[]>;

package/utils/query-helpers.util.d.ts

@@ -6,6 +6,12 @@ export interface ICompanyFilterConfig {
     columnName?: string;
 }
 export declare function applyCompanyFilter<T extends ObjectLiteral>(query: SelectQueryBuilder<T>, config: ICompanyFilterConfig, user: ILoggedUserInfo | null | undefined): SelectQueryBuilder<T>;
+export interface IBranchFilterConfig {
+    entityAlias: string;
+    columnName?: string;
+    includeUnassigned?: boolean;
+}
+export declare function applyBranchFilter<T extends ObjectLiteral>(query: SelectQueryBuilder<T>, config: IBranchFilterConfig, branchIds: ReadonlyArray<string | null | undefined>): SelectQueryBuilder<T>;
 export declare function buildCompanyWhereCondition<T extends Record<string, unknown>>(baseWhere: T, isCompanyFeatureEnabled: boolean, user: ILoggedUserInfo | null | undefined): T & {
     companyId?: string;
 };

package/utils/safe-regex.util.d.ts

@@ -0,0 +1,10 @@
+import { RE2JS } from 're2js';
+export declare const SAFE_REGEX_LIMITS: {
+    readonly MAX_PATTERN_LENGTH: 500;
+    readonly MAX_INPUT_LENGTH: 10000;
+    readonly MAX_REPEAT: 100;
+    readonly MAX_REPEAT_EXPANSION: 300;
+};
+export type SafeRegexProblem = 'too_long' | 'invalid' | 'too_complex';
+export declare function safeRegexProblem(pattern: string): SafeRegexProblem | null;
+export declare function compileSafeRegex(pattern: string): RE2JS;