@rytass/bpm-core-shared 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -8,6 +8,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Releases are managed by [`nx release`](https://nx.dev/recipes/nx-release) with
 Conventional Commits — see `nx.json` for the release config.
 
+## 0.6.0 — 2026-08-04
+
+### Added
+
+- **`preferClosestOrgUnit` optional flag** on the `ORG_MANAGER` and
+  `ORG_UNIT_MANAGER` variants of `ApproverResolver`. When enabled, the
+  workflow engine resolves only the deepest org-unit-level manager rules
+  on the winning priority tier, so ancestor-level catch-all rules do not
+  dilute the approver list. Defaults to `false` (unchanged behavior).
+  `parseApproverResolver` in `workflow-toolset.ts` parses the new field.
+
+### Why a minor
+
+New optional type field — backward compatible, additive.
+
+## 0.5.1 — 2026-07-06
+
+### Fixed
+
+- **Broken 0.5.0 tarball.** 0.5.0 was published from the project source root, so
+  the npm tarball shipped only TypeScript sources with no compiled `.js`/`.d.ts`
+  while `main`/`exports` point at `./src/index.js`. 0.5.1 is republished from the
+  build output (`dist/libs/shared`). Configured `nx-release-publish` with
+  `packageRoot: dist/libs/shared`. No source changes.
+
 ## 0.5.0 — 2026-07-06
 
 No source changes. Version aligned with `@rytass/bpm-core-client` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-shared",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shared TypeScript contracts for the Rytass BPM approval workflow stack (workflow, form, condition, identity, organization, status types).",
   "keywords": [
     "bpm",
@@ -94,5 +94,6 @@
   },
   "dependencies": {
     "tslib": "^2.3.0"
-  }
+  },
+  "type": "commonjs"
 }

package/src/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/condition"), exports);
+tslib_1.__exportStar(require("./lib/form"), exports);
+tslib_1.__exportStar(require("./lib/identity"), exports);
+tslib_1.__exportStar(require("./lib/organization"), exports);
+tslib_1.__exportStar(require("./lib/status"), exports);
+tslib_1.__exportStar(require("./lib/workflow"), exports);
+tslib_1.__exportStar(require("./lib/workflow-graph"), exports);
+tslib_1.__exportStar(require("./lib/workflow-command"), exports);
+tslib_1.__exportStar(require("./lib/workflow-toolset"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/shared/src/index.ts"],"names":[],"mappings":";;;AAAA,0DAAgC;AAChC,qDAA2B;AAC3B,yDAA+B;AAC/B,6DAAmC;AACnC,uDAA6B;AAC7B,yDAA+B;AAC/B,+DAAqC;AACrC,iEAAuC;AACvC,iEAAuC"}

package/src/lib/condition.d.ts

@@ -0,0 +1,43 @@
+export type ConditionContextType = 'INITIATOR_POLICY' | 'ENTRY_CONDITION' | 'FLOW_CONDITION' | 'APPROVER_RESOLVER' | 'FORM_FIELD_CONDITION' | 'DELEGATION_CONDITION';
+export interface SubjectContext {
+    readonly customFields: Readonly<Record<string, unknown>>;
+    readonly email: string;
+    readonly memberId: string;
+    readonly name: string;
+    readonly org: OrgContext;
+    readonly position: PositionContext;
+    readonly roles: readonly string[];
+}
+export interface OrgContext {
+    readonly code: string;
+    readonly costCenter?: string;
+    readonly id: string;
+    readonly location?: string;
+    readonly name: string;
+    readonly parentId: string | null;
+    readonly path: readonly string[];
+    readonly type: string;
+}
+export interface PositionContext {
+    readonly code: string;
+    readonly id: string;
+    readonly level: number;
+    readonly name: string;
+}
+export interface EnvContext {
+    readonly now: string;
+}
+export interface InstanceContext {
+    readonly id: string;
+    readonly startedAt: string;
+    readonly templateId: string;
+    readonly templateVersion: number;
+}
+export interface LastDecisionContext {
+    readonly action: 'approved' | 'rejected' | 'returned';
+    readonly comment: string;
+    readonly decidedAt: string;
+    readonly decidedBy: SubjectContext;
+    readonly nodeId: string;
+    readonly taskId: string;
+}

package/src/lib/condition.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=condition.js.map

package/src/lib/condition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition.js","sourceRoot":"","sources":["../../../../../libs/shared/src/lib/condition.ts"],"names":[],"mappings":""}

package/src/lib/form.d.ts

@@ -0,0 +1,48 @@
+export interface FormDefinitionSchema {
+    readonly fields: readonly FormFieldDefinition[];
+    readonly schemaVersion: 1;
+}
+export type FormFieldDefinition = TextFieldDefinition | NumberFieldDefinition | DateFieldDefinition | SelectFieldDefinition | BooleanFieldDefinition | FileUploadFieldDefinition;
+interface BaseFormFieldDefinition<TType extends string> {
+    readonly defaultValue?: FormFieldValue;
+    readonly description?: string;
+    readonly fieldKey: string;
+    readonly label: string;
+    readonly placeholder?: string;
+    readonly readonlyWhen?: string;
+    readonly required: boolean;
+    readonly requiredWhen?: string;
+    readonly type: TType;
+    readonly visibleWhen?: string;
+}
+export type FormFieldValue = boolean | number | string | readonly string[] | null;
+export type TextFieldDefinition = BaseFormFieldDefinition<'text' | 'textarea'> & {
+    readonly maxLength?: number;
+    readonly minLength?: number;
+};
+export type NumberFieldDefinition = BaseFormFieldDefinition<'number' | 'money'> & {
+    readonly maximum?: number;
+    readonly minimum?: number;
+};
+export type DateFieldDefinition = BaseFormFieldDefinition<'date' | 'datetime'>;
+export type SelectFieldDefinition = BaseFormFieldDefinition<'select' | 'radio' | 'checkbox'> & {
+    readonly options: readonly FormFieldOption[];
+};
+export interface FormFieldOption {
+    readonly label: string;
+    readonly value: string;
+}
+export type BooleanFieldDefinition = BaseFormFieldDefinition<'boolean'>;
+export type FileUploadFieldDefinition = BaseFormFieldDefinition<'file_upload'> & {
+    readonly acceptedMimeTypes?: readonly string[];
+    readonly maxFiles?: number;
+};
+export interface FormUiSchema {
+    readonly layout: readonly FormLayoutItem[];
+    readonly schemaVersion: 1;
+}
+export interface FormLayoutItem {
+    readonly fieldKey: string;
+    readonly width: 'FULL' | 'HALF' | 'THIRD';
+}
+export {};

package/src/lib/form.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=form.js.map

package/src/lib/form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.js","sourceRoot":"","sources":["../../../../../libs/shared/src/lib/form.ts"],"names":[],"mappings":""}

package/src/lib/identity.d.ts

@@ -0,0 +1,24 @@
+export interface MemberMetadata {
+    readonly memberId: string;
+    readonly name: string;
+    readonly email: string;
+    /**
+     * Opaque host-shaped JSON. BPM stores the object verbatim, serializes
+     * it back to GraphQL clients as `MemberProfile.customFieldsJson`, and
+     * never introspects keys — anything the host puts here flows through
+     * unchanged. Hosts using `createBPMMemberBaseResolverProvider` populate
+     * this field via the `options.readCustomFields?.(member)` hook;
+     * standalone `BPMMemberResolver` implementations return whatever shape
+     * the consumer UI needs. Use it as a side channel for picker labels,
+     * org context strings, avatar URLs, or any other host-specific
+     * metadata that should appear in member-display UIs.
+     */
+    readonly customFields: Readonly<Record<string, unknown>>;
+}
+export interface MemberMetadataCacheEntry {
+    readonly id: string;
+    readonly memberId: string;
+    readonly metadata: MemberMetadata;
+    readonly fetchedAt: string;
+    readonly expiresAt: string;
+}

package/src/lib/identity.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=identity.js.map

package/src/lib/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../../../../libs/shared/src/lib/identity.ts"],"names":[],"mappings":""}

package/src/lib/organization.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Org-unit type — matches the BPM GraphQL `OrgUnitType` enum SDL names
+ * (UPPERCASE). The server stores the value lower-cased internally
+ * (`'company'` etc. in the database row), but every read and write
+ * across the GraphQL wire and the REST surface uses the UPPERCASE form.
+ *
+ * Consumers of `@rytass/bpm-core-client/organization` must pass these
+ * UPPERCASE literals to `createOrgUnit` / `updateOrgUnit` (and the
+ * `readOrganizationDashboard` `orgUnitType` filter), and will receive
+ * UPPERCASE values back on `OrgUnitRecord.type`.
+ */
+export type OrgUnitType = 'COMPANY' | 'DIVISION' | 'DEPARTMENT' | 'TEAM';
+export type ManagerResolutionScopeType = 'MEMBER' | 'ORG_UNIT' | 'POSITION';
+export interface OrgUnit {
+    readonly id: string;
+    readonly parentId: string | null;
+    readonly code: string;
+    readonly name: string;
+    readonly type: OrgUnitType;
+    readonly path: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+export interface Position {
+    readonly id: string;
+    readonly code: string;
+    readonly name: string;
+    readonly level: number;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+export interface Membership {
+    readonly id: string;
+    readonly memberId: string;
+    readonly orgUnitId: string;
+    readonly positionId: string | null;
+    readonly isPrimary: boolean;
+    readonly effectiveFrom: string;
+    readonly effectiveTo: string | null;
+}
+export interface ManagerResolution {
+    readonly id: string;
+    readonly scopeType: ManagerResolutionScopeType;
+    readonly scopeId: string;
+    readonly managerMemberId: string;
+    readonly priority: number;
+    readonly effectiveFrom: string;
+    readonly effectiveTo: string | null;
+}

package/src/lib/organization.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=organization.js.map

package/src/lib/organization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization.js","sourceRoot":"","sources":["../../../../../libs/shared/src/lib/organization.ts"],"names":[],"mappings":""}

package/src/lib/status.d.ts

@@ -0,0 +1,7 @@
+export type VersionStatus = 'DRAFT' | 'PUBLISHED' | 'ARCHIVED';
+export type ApprovalInstanceState = 'DRAFT' | 'RUNNING' | 'APPROVED' | 'REJECTED' | 'RETURNED' | 'CANCELLED' | 'EXPIRED';
+export type WorkflowTokenStatus = 'ACTIVE' | 'WAITING' | 'CONSUMED';
+export type TaskStatus = 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'TRANSFERRED' | 'CANCELLED';
+export type TaskDecisionAction = 'APPROVED' | 'REJECTED' | 'RETURNED' | 'TRANSFERRED';
+export type DelegationRuleStatus = 'ACTIVE' | 'REVOKED' | 'EXPIRED';
+export type DelegationScopeType = 'ALL' | 'TEMPLATE_LIST' | 'CONDITION_BASED';

package/src/lib/status.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=status.js.map

package/src/lib/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../../../libs/shared/src/lib/status.ts"],"names":[],"mappings":""}

package/src/lib/workflow-command.d.ts

@@ -0,0 +1,156 @@
+import { FormDefinitionSchema } from './form';
+import { ApproverResolver, ReturnResubmitStrategy, ServiceAction, WorkflowDefinition, WorkflowEdgeConditionOperator, WorkflowNodeTriggerMode } from './workflow';
+import { NodePaletteType, WorkflowEdgeIdFactory } from './workflow-graph';
+/**
+ * The serialisable command layer that the template designer — and the LLM
+ * assistant — drive the workflow through. Every mutation a user can perform on
+ * the canvas, node palette, or property form is expressed as one of these
+ * commands, and {@link applyWorkflowCommand} is the single pure reducer that
+ * applies them. The React controller and the LLM tool runtime both dispatch the
+ * exact same commands, guaranteeing the assistant can do anything a user can.
+ */
+/** Everything the reducer needs as the single source of truth. */
+export interface WorkflowDesignerState {
+    /** Form schema bound to the template; needed to compile edge conditions. */
+    readonly formSchema: FormDefinitionSchema | null;
+    readonly definition: WorkflowDefinition;
+    readonly editingEdgeId: string | null;
+    readonly formDefinitionVersionId: string | null;
+    readonly initiatorPolicyCel: string | null;
+    readonly selectedEdgeIds: readonly string[];
+    readonly selectedNodeId: string | null;
+}
+/** Where a newly added node should be wired in. */
+export interface WorkflowNodeAnchor {
+    /** Insert the node onto this edge, splitting it. */
+    readonly edgeId?: string | null;
+    /** Insert the node after this node. */
+    readonly afterNodeId?: string | null;
+}
+export type WorkflowCommand = {
+    readonly type: 'addNode';
+    readonly nodeType: NodePaletteType;
+    readonly anchor?: WorkflowNodeAnchor;
+} | {
+    readonly type: 'renameNode';
+    readonly nodeId: string;
+    readonly label: string;
+} | {
+    readonly type: 'deleteNode';
+    readonly nodeId: string;
+} | {
+    readonly type: 'setNodeTriggerMode';
+    readonly nodeId: string;
+    readonly triggerMode: WorkflowNodeTriggerMode;
+} | {
+    readonly type: 'setUserTaskApprover';
+    readonly nodeId: string;
+    readonly approverResolver: ApproverResolver;
+} | {
+    readonly type: 'setUserTaskReturnResubmitStrategy';
+    readonly nodeId: string;
+    readonly resubmitStrategy: ReturnResubmitStrategy;
+} | {
+    readonly type: 'setUserTaskOptions';
+    readonly nodeId: string;
+    readonly allowAddSigner?: boolean;
+    readonly allowReject?: boolean;
+    readonly allowTransfer?: boolean;
+    readonly description?: string;
+} | {
+    readonly type: 'setServiceAction';
+    readonly nodeId: string;
+    readonly action: ServiceAction;
+} | {
+    readonly type: 'setEndState';
+    readonly nodeId: string;
+    readonly endState: 'APPROVED' | 'REJECTED';
+} | {
+    readonly type: 'connectEdge';
+    readonly source: string;
+    readonly target: string;
+} | {
+    readonly type: 'deleteEdge';
+    readonly edgeId: string;
+} | {
+    readonly type: 'setEdgeCondition';
+    readonly edgeId: string;
+    readonly fieldKey?: string | null;
+    readonly operator?: WorkflowEdgeConditionOperator | null;
+    readonly value?: string | null;
+} | {
+    readonly type: 'setEdgeDefault';
+    readonly edgeId: string;
+    readonly isDefault: boolean;
+} | {
+    readonly type: 'bindForm';
+    readonly formDefinitionVersionId: string | null;
+    readonly formSchema: FormDefinitionSchema | null;
+} | {
+    readonly type: 'setInitiatorPolicyCel';
+    readonly cel: string | null;
+} | {
+    readonly type: 'selectNode';
+    readonly nodeId: string | null;
+} | {
+    readonly type: 'selectEdges';
+    readonly edgeIds: readonly string[];
+} | {
+    readonly type: 'autoLayout';
+};
+/** High-level intents that fold into a sequence of primitive commands. */
+export type WorkflowMacroCommand = {
+    readonly type: 'insertApprovalStep';
+    readonly approverResolver: ApproverResolver;
+    readonly label?: string;
+    readonly anchor?: WorkflowNodeAnchor;
+} | {
+    readonly type: 'insertNotification';
+    readonly action: ServiceAction;
+    readonly label?: string;
+    readonly anchor?: WorkflowNodeAnchor;
+} | {
+    readonly type: 'insertConditionalBranch';
+    readonly label?: string;
+    readonly anchor?: WorkflowNodeAnchor;
+};
+export type AnyWorkflowCommand = WorkflowCommand | WorkflowMacroCommand;
+/** Side-effect hints for the React controller (pixel layout/viewport). */
+export interface WorkflowCommandEffects {
+    /** Topology changed — controller should re-run dagre layout + viewport. */
+    readonly layout: boolean;
+}
+export interface WorkflowCommandResult {
+    readonly state: WorkflowDesignerState;
+    /** Whether the command actually changed state. */
+    readonly changed: boolean;
+    /** Human-facing reason the command was a no-op / rejected, else null. */
+    readonly error: string | null;
+    /** Post-apply validation issue (same text the Save button uses), else null. */
+    readonly issue: string | null;
+    readonly effects: WorkflowCommandEffects;
+}
+export interface WorkflowCommandOptions {
+    /** Injectable edge id factory for deterministic runs (tests, replay). */
+    readonly createEdgeId?: WorkflowEdgeIdFactory;
+}
+/**
+ * Apply a single primitive command. Pure: same input → same output (given a
+ * deterministic edge id factory). Topology-changing commands set
+ * `effects.layout` so the controller can run dagre afterwards.
+ */
+export declare function applyWorkflowCommand(state: WorkflowDesignerState, command: WorkflowCommand, options?: WorkflowCommandOptions): WorkflowCommandResult;
+/**
+ * Apply a high-level macro by expanding it into primitive commands. The added
+ * node's id is deterministic (`<nodeType>_<nextIndex>`), so follow-up commands
+ * can target it without depending on the post-insert selection.
+ */
+export declare function applyWorkflowMacroCommand(state: WorkflowDesignerState, command: WorkflowMacroCommand, options?: WorkflowCommandOptions): WorkflowCommandResult;
+/** Apply a batch of primitive commands in order, threading state. */
+export declare function applyWorkflowCommands(state: WorkflowDesignerState, commands: readonly WorkflowCommand[], options?: WorkflowCommandOptions): WorkflowCommandResult;
+/**
+ * Expand a high-level macro into the primitive command sequence that realises
+ * it. The next node id is derived from the same deterministic rule
+ * {@link applyAddNode} uses, so post-add commands can target it directly.
+ */
+export declare function expandMacroCommand(state: WorkflowDesignerState, command: WorkflowMacroCommand): readonly WorkflowCommand[];