@zeniai/client-epic-state 5.1.0-betaSS3 → 5.1.0

package/lib/entity/approvalRule/approvalRuleConflict.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectRuleOverlap = detectRuleOverlap;
+function detectRuleOverlap({ candidateCriteria, existingRules, excludeRuleId, }) {
+    const candidateAmount = pickAmount(candidateCriteria);
+    const candidateVendor = pickVendor(candidateCriteria);
+    const candidateDepartment = pickDepartment(candidateCriteria);
+    const overlaps = [];
+    for (const rule of existingRules) {
+        if (rule.approvalRuleId === excludeRuleId) {
+            continue;
+        }
+        if (rule.isFallback === true) {
+            continue;
+        }
+        const ruleVendor = pickVendor(rule.criteria);
+        const ruleDepartment = pickDepartment(rule.criteria);
+        if (!areVendorCriteriaEqual(candidateVendor, ruleVendor)) {
+            continue;
+        }
+        if (!areDepartmentCriteriaEqual(candidateDepartment, ruleDepartment)) {
+            continue;
+        }
+        const ruleAmount = pickAmount(rule.criteria);
+        if (amountsOverlap(candidateAmount, ruleAmount)) {
+            overlaps.push({ conflictingRule: rule });
+        }
+    }
+    return overlaps;
+}
+const pickAmount = (criteria) => criteria.find((c) => c.type === 'amount');
+const pickVendor = (criteria) => criteria.find((c) => c.type === 'vendor');
+const pickDepartment = (criteria) => criteria.find((c) => c.type === 'department');
+const areVendorCriteriaEqual = (a, b) => {
+    if (a == null && b == null) {
+        return true;
+    }
+    if (a == null || b == null) {
+        return false;
+    }
+    if (a.operator !== b.operator) {
+        return false;
+    }
+    return idsEqual(a.vendorIds, b.vendorIds);
+};
+const areDepartmentCriteriaEqual = (a, b) => {
+    if (a == null && b == null) {
+        return true;
+    }
+    if (a == null || b == null) {
+        return false;
+    }
+    if (a.operator !== b.operator) {
+        return false;
+    }
+    return idsEqual(a.departmentIds, b.departmentIds);
+};
+const idsEqual = (a, b) => {
+    if (a.length !== b.length) {
+        return false;
+    }
+    const aSorted = [...a].sort();
+    const bSorted = [...b].sort();
+    return aSorted.every((id, i) => id === bSorted[i]);
+};
+const amountsOverlap = (a, b) => {
+    // Absent amount criteria covers the whole real line, so any
+    // pairing involving an absent one is a guaranteed overlap.
+    if (a == null || b == null) {
+        return true;
+    }
+    const aLow = a.min?.amount ?? Number.NEGATIVE_INFINITY;
+    const aHigh = a.max?.amount ?? Number.POSITIVE_INFINITY;
+    const bLow = b.min?.amount ?? Number.NEGATIVE_INFINITY;
+    const bHigh = b.max?.amount ?? Number.POSITIVE_INFINITY;
+    return Math.max(aLow, bLow) <= Math.min(aHigh, bHigh);
+};

package/lib/entity/approvalRule/approvalRulePayload.d.ts

@@ -1,11 +1,27 @@
 import { ApprovalRule } from './approvalRuleState';
+/**
+ * Condition Payload — one entry inside criteria.conditions[].
+ *
+ * field examples: 'amount' | 'vendor_id' | 'department_id'
+ * type examples:  'gte' | 'lte' | 'eq' | 'in' | 'not_in'
+ * value: number for amount comparisons; string[] for in / not_in lookups.
+ */
+export interface ConditionPayload {
+    field: string;
+    type: string;
+    value: number | string[];
+}
+/**
+ * Criteria Payload — list of conditions joined by `criteria_operator`.
+ *
+ * `currency_code` / `currency_symbol` apply to amount conditions inside
+ * `conditions[]`. Kept here pending confirmation that they should remain.
+ */
 export interface CriteriaPayload {
+    conditions: ConditionPayload[];
+    criteria_operator: string;
     currency_code: string;
     currency_symbol: string;
-    min: number;
-    range_entity: string;
-    type: string;
-    max?: number | null;
 }
 export interface ActorPayload {
     type: string;
@@ -25,11 +41,24 @@ export interface StepPayload {
 export interface ApprovalRulePayload {
     approval_rule_id: string;
     create_time: string;
-    criteria: CriteriaPayload[];
+    criteria: CriteriaPayload;
     entity_type: string;
     name: string | null;
     steps: StepPayload[];
     update_time: string;
+    are_approvals_serialized?: boolean;
+    description?: string | null;
+    is_fallback?: boolean;
+    /**
+     * Approval Rules 3.0 — when `true`, the rule enforces separation of
+     * duties (a user can't approve their own request even if they are
+     * also an approver). The list-page rule card surfaces this as a
+     * green "Separation of duties" capsule.
+     */
+    is_separation_of_duty_enabled?: boolean;
+    pending_approvals_count?: number;
+    pending_entity_approval_update_status?: string;
+    priority?: number;
     version?: number | string;
 }
 /**

package/lib/entity/approvalRule/approvalRulePayload.js

@@ -17,19 +17,154 @@ const toApprovalRule = (payload) => ({
     version: payload.version,
     criteria: toApprovalCriteria(payload.criteria),
     steps: toApprovalSteps(payload.steps),
+    description: payload.description ?? undefined,
+    priority: payload.priority,
+    isFallback: payload.is_fallback ?? false,
+    separationOfDuties: payload.is_separation_of_duty_enabled ?? false,
+    areApprovalsSerialized: payload.are_approvals_serialized,
+    pendingApprovalsCount: payload.pending_approvals_count,
+    pendingEntityApprovalUpdateStatus: payload.pending_entity_approval_update_status,
 });
 exports.toApprovalRule = toApprovalRule;
+/**
+ * Maps the wire-level criteria block into the state-side discriminated
+ * `Criteria[]` union.
+ *
+ * The wire keeps each condition as a flat row inside `conditions[]`.
+ * Amount comparisons can show up as a `gte` only, a `lte` only, or a
+ * `gte` + `lte` pair — those collapse into a single AmountCriteria whose
+ * `comparator` is `greater_than`, `less_than`, or `range` respectively.
+ *
+ * Vendor and department conditions map one-to-one: `in` becomes `is`,
+ * `not_in` becomes `is_not`.
+ *
+ * Resilient to two forms of upstream drift:
+ *  - Missing / null criteria → returns [].
+ *  - Legacy criteria shape (array of amount-range objects, the pre-3.0
+ *    wire) → converted to an AmountCriteria so existing rules in production
+ *    still render while the backend rolls out.
+ */
 const toApprovalCriteria = (payload) => {
-    return payload.map((criteria) => ({
-        rangeType: criteria.type,
-        rangeEntity: criteria.range_entity,
-        range: {
-            min: (0, amount_1.toAmount)(criteria.min, criteria.currency_code, criteria.currency_symbol),
-            max: criteria.max != null
-                ? (0, amount_1.toAmount)(criteria.max, criteria.currency_code, criteria.currency_symbol)
-                : undefined,
-        },
-    }));
+    if (payload == null) {
+        return [];
+    }
+    if (Array.isArray(payload)) {
+        // Legacy pre-3.0 wire: an array of amount-range entries.
+        return legacyAmountRangeToCriteria(payload);
+    }
+    if (!Array.isArray(payload.conditions)) {
+        return [];
+    }
+    const results = [];
+    const amountCriteria = toAmountCriteria(payload);
+    if (amountCriteria != null) {
+        results.push(amountCriteria);
+    }
+    payload.conditions
+        .filter((condition) => condition.field === 'vendor_id')
+        .forEach((condition) => {
+        const vendor = toVendorCriteria(condition);
+        if (vendor != null) {
+            results.push(vendor);
+        }
+    });
+    payload.conditions
+        .filter((condition) => condition.field === 'department_id')
+        .forEach((condition) => {
+        const department = toDepartmentCriteria(condition);
+        if (department != null) {
+            results.push(department);
+        }
+    });
+    return results;
+};
+const legacyAmountRangeToCriteria = (legacy) => {
+    if (legacy.length === 0) {
+        return [];
+    }
+    // The state-side 'Criteria[]' model allows at most one
+    // 'AmountCriteria' per rule (see 'approvalRuleState.ts'). The legacy
+    // wire was an array, so a multi-entry payload can't be represented
+    // here without losing data. Read the first entry and log a warning
+    // if production rules ever ship more — that would signal a backend
+    // regression we want to catch early rather than silently truncating.
+    if (legacy.length > 1) {
+        console.warn('[approvalRulePayload] legacyAmountRangeToCriteria: received ' +
+            legacy.length +
+            ' entries but the state model only supports one; using the ' +
+            'first entry and dropping the rest.');
+    }
+    const first = legacy[0] ?? {};
+    const currency = first.currency_code ?? 'USD';
+    const symbol = first.currency_symbol ?? '$';
+    const min = typeof first.min === 'number'
+        ? (0, amount_1.toAmount)(first.min, currency, symbol)
+        : undefined;
+    const max = typeof first.max === 'number'
+        ? (0, amount_1.toAmount)(first.max, currency, symbol)
+        : undefined;
+    if (min == null && max == null) {
+        return [];
+    }
+    const comparator = min != null && max != null
+        ? 'range'
+        : min != null
+            ? 'greater_than'
+            : 'less_than';
+    return [{ type: 'amount', comparator, min, max }];
+};
+const toAmountCriteria = (payload) => {
+    if (!Array.isArray(payload.conditions)) {
+        return undefined;
+    }
+    const amountConditions = payload.conditions.filter((condition) => condition.field === 'amount');
+    // Approval Rules 3.0 — an 'eq' condition represents min === max. Fold
+    // it into both finders so it decodes as comparator: 'range' (closed
+    // single-point) rather than 'greater_than' (open upper).
+    const gteCondition = amountConditions.find((condition) => condition.type === 'gte' || condition.type === 'eq');
+    const lteCondition = amountConditions.find((condition) => condition.type === 'lte' || condition.type === 'eq');
+    if (gteCondition == null && lteCondition == null) {
+        return undefined;
+    }
+    const currencyCode = payload.currency_code ?? 'USD';
+    const currencySymbol = payload.currency_symbol ?? '$';
+    const min = typeof gteCondition?.value === 'number'
+        ? (0, amount_1.toAmount)(gteCondition.value, currencyCode, currencySymbol)
+        : undefined;
+    const max = typeof lteCondition?.value === 'number'
+        ? (0, amount_1.toAmount)(lteCondition.value, currencyCode, currencySymbol)
+        : undefined;
+    let comparator;
+    if (min != null && max != null) {
+        comparator = 'range';
+    }
+    else if (min != null) {
+        comparator = 'greater_than';
+    }
+    else {
+        comparator = 'less_than';
+    }
+    return { type: 'amount', comparator, min, max };
+};
+const toVendorCriteria = (condition) => {
+    if (!Array.isArray(condition.value)) {
+        return undefined;
+    }
+    return {
+        type: 'vendor',
+        operator: condition.type === 'not_in' ? 'is_not' : 'is',
+        vendorIds: condition.value,
+    };
+};
+const toDepartmentCriteria = (condition) => {
+    if (!Array.isArray(condition.value)) {
+        return undefined;
+    }
+    return {
+        type: 'department',
+        operator: condition.type === 'not_in' ? 'is_not' : 'is',
+        departmentIds: condition.value,
+    };
 };
 const toApprovalSteps = (payload) => {
     return payload.map((step) => ({

package/lib/entity/approvalRule/approvalRuleSelector.d.ts

@@ -1,4 +1,28 @@
 import { ID } from '../../commonStateTypes/common';
-import { ApprovalRule, ApprovalRuleState } from './approvalRuleState';
+import { EntityType } from '../entityApprovalStatus/entityApprovalStatusState';
+import { AmountCriteria, ApprovalRule, ApprovalRuleState, Criteria, DepartmentCriteria, VendorCriteria } from './approvalRuleState';
 export declare function getApprovalRuleById(approvalRuleState: ApprovalRuleState, approvalRuleId: ID): ApprovalRule | undefined;
 export declare function getApprovalRulesByIds(approvalRuleState: ApprovalRuleState, approvalRuleIds: ID[]): ApprovalRule[];
+/**
+ * Returns the amount-range portion of a rule's criteria, if any.
+ *
+ * Use this whenever a caller needs to read amount min/max from the new
+ * discriminated `Criteria` union without inlining a type guard.
+ */
+export declare function getAmountCriteria(criteria: Criteria[]): AmountCriteria | undefined;
+export declare function getVendorCriteria(criteria: Criteria[]): VendorCriteria | undefined;
+export declare function getDepartmentCriteria(criteria: Criteria[]): DepartmentCriteria | undefined;
+/**
+ * Returns all rules of the given entityType, sorted by `priority` ascending.
+ *
+ * Rules without a `priority` value sort to the end (treated as Infinity).
+ * Use this for the list page where rules render in evaluation order.
+ */
+export declare function getApprovalRulesByEntityType(approvalRuleState: ApprovalRuleState, entityType: EntityType): ApprovalRule[];
+/**
+ * Returns the tenant's fallback rule for the given entityType, if one exists.
+ *
+ * The fallback rule is shown by the "fallback engine active" banner on the
+ * list page and is used to handle bills/reimbursements that match no other rule.
+ */
+export declare function getFallbackApprovalRule(approvalRuleState: ApprovalRuleState, entityType: EntityType): ApprovalRule | undefined;

package/lib/entity/approvalRule/approvalRuleSelector.js

@@ -2,6 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getApprovalRuleById = getApprovalRuleById;
 exports.getApprovalRulesByIds = getApprovalRulesByIds;
+exports.getAmountCriteria = getAmountCriteria;
+exports.getVendorCriteria = getVendorCriteria;
+exports.getDepartmentCriteria = getDepartmentCriteria;
+exports.getApprovalRulesByEntityType = getApprovalRulesByEntityType;
+exports.getFallbackApprovalRule = getFallbackApprovalRule;
 function getApprovalRuleById(approvalRuleState, approvalRuleId) {
     return approvalRuleState.approvalRuleById[approvalRuleId] ?? undefined;
 }
@@ -11,3 +16,38 @@ function getApprovalRulesByIds(approvalRuleState, approvalRuleIds) {
         .filter((value) => value != null);
     return approvalRulesByIds;
 }
+/**
+ * Returns the amount-range portion of a rule's criteria, if any.
+ *
+ * Use this whenever a caller needs to read amount min/max from the new
+ * discriminated `Criteria` union without inlining a type guard.
+ */
+function getAmountCriteria(criteria) {
+    return criteria.find((c) => c.type === 'amount');
+}
+function getVendorCriteria(criteria) {
+    return criteria.find((c) => c.type === 'vendor');
+}
+function getDepartmentCriteria(criteria) {
+    return criteria.find((c) => c.type === 'department');
+}
+/**
+ * Returns all rules of the given entityType, sorted by `priority` ascending.
+ *
+ * Rules without a `priority` value sort to the end (treated as Infinity).
+ * Use this for the list page where rules render in evaluation order.
+ */
+function getApprovalRulesByEntityType(approvalRuleState, entityType) {
+    return Object.values(approvalRuleState.approvalRuleById)
+        .filter((rule) => rule.entityType === entityType)
+        .sort((a, b) => (a.priority ?? Infinity) - (b.priority ?? Infinity));
+}
+/**
+ * Returns the tenant's fallback rule for the given entityType, if one exists.
+ *
+ * The fallback rule is shown by the "fallback engine active" banner on the
+ * list page and is used to handle bills/reimbursements that match no other rule.
+ */
+function getFallbackApprovalRule(approvalRuleState, entityType) {
+    return Object.values(approvalRuleState.approvalRuleById).find((rule) => rule.entityType === entityType && rule.isFallback === true);
+}

package/lib/entity/approvalRule/approvalRuleState.d.ts

@@ -25,14 +25,48 @@ export interface Actor {
     subType?: AttributeType | RoleType;
     userId?: ID;
 }
-export interface Criteria {
-    range: {
-        min: Amount;
-        max?: Amount;
-    };
-    rangeEntity: string;
-    rangeType: string;
+/**
+ * Approval rule criteria — discriminated union over the three condition
+ * types the wire format supports: amount, vendor, and department.
+ *
+ * State-side, each rule carries a `Criteria[]` with at most one variant of
+ * each kind (e.g. one AmountCriteria + one VendorCriteria + one DepartmentCriteria).
+ *
+ * Form-side, the rule create/edit form uses `ApprovalRuleFormCriteria`
+ * (defined in commonState) — a structured object with named slots for
+ * amount/vendor/department. Epics translate between the two.
+ */
+export type AmountComparator = 'greater_than' | 'less_than' | 'range';
+export interface AmountCriteria {
+    comparator: AmountComparator;
+    type: 'amount';
+    /** Upper bound. Present for `less_than` and `range`. */
+    max?: Amount;
+    /** Lower bound. Present for `greater_than` and `range`. */
+    min?: Amount;
+}
+export interface VendorCriteria {
+    operator: 'is' | 'is_not';
+    type: 'vendor';
+    vendorIds: ID[];
 }
+export interface DepartmentCriteria {
+    departmentIds: ID[];
+    operator: 'is' | 'is_not';
+    type: 'department';
+}
+export type Criteria = AmountCriteria | VendorCriteria | DepartmentCriteria;
+/**
+ * Approval Rules 3.0 — canonical discriminator across the three
+ * condition variants. Derived from the `Criteria` union's `type`
+ * field so it can't drift from the underlying data model.
+ *
+ * Used by the unified `ConditionRow` UI component to switch which
+ * variant body to render, and by chip-rendering helpers on the list
+ * page to pick a label format. Consumers should import this type
+ * rather than redeclaring the three string literals locally.
+ */
+export type ConditionType = Criteria['type'];
 export interface Step {
     actors: Actor[];
     operator: StepOperatorType;
@@ -51,7 +85,25 @@ export interface ApprovalRule {
     entityType: EntityType;
     steps: Step[];
     updateTime: ZeniDate;
+    /** Backend bookkeeping: whether approval steps must run serialized. */
+    areApprovalsSerialized?: boolean;
+    /** Free-text description shown beneath the rule name on the list page. */
+    description?: string;
+    /** True when this rule is the tenant's default fallback rule. */
+    isFallback?: boolean;
     name?: string;
+    /** Backend bookkeeping: number of entities currently pending against this rule. */
+    pendingApprovalsCount?: number;
+    /** Backend bookkeeping: status of background updates against this rule. */
+    pendingEntityApprovalUpdateStatus?: string;
+    /** Rule's position in the evaluation order; lower number = higher priority. */
+    priority?: number;
+    /**
+     * When on, the creator of a bill/reimbursement cannot auto-approve
+     * their own request even if they are also an approver. Backend spec
+     * is still pending — kept optional for now.
+     */
+    separationOfDuties?: boolean;
     version?: number | string;
 }
 export interface Approvers {