@objectstack/plugin-approvals 13.0.0 → 14.3.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/plugin-approvals@13.0.0 build /home/runner/work/framework/framework/packages/plugins/plugin-approvals
+> @objectstack/plugin-approvals@14.3.0 build /home/runner/work/framework/framework/packages/plugins/plugin-approvals
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     120.30 KB
-ESM dist/index.mjs.map 215.93 KB
-ESM ⚡️ Build success in 318ms
-CJS dist/index.js     121.97 KB
-CJS dist/index.js.map 217.13 KB
-CJS ⚡️ Build success in 321ms
+CJS dist/index.js     123.99 KB
+CJS dist/index.js.map 220.47 KB
+CJS ⚡️ Build success in 241ms
+ESM dist/index.mjs     122.33 KB
+ESM dist/index.mjs.map 219.27 KB
+ESM ⚡️ Build success in 244ms
 DTS Build start
-DTS ⚡️ Build success in 17165ms
-DTS dist/index.d.mts 381.76 KB
-DTS dist/index.d.ts  381.76 KB
+DTS ⚡️ Build success in 28424ms
+DTS dist/index.d.mts 382.64 KB
+DTS dist/index.d.ts  382.64 KB

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # @objectstack/plugin-approvals
 
+## 14.3.0
+
+### Patch Changes
+
+- Updated dependencies [2a71f48]
+- Updated dependencies [02f6af4]
+- Updated dependencies [c1064f1]
+  - @objectstack/platform-objects@14.3.0
+  - @objectstack/spec@14.3.0
+  - @objectstack/core@14.3.0
+  - @objectstack/formula@14.3.0
+  - @objectstack/metadata-core@14.3.0
+
+## 14.2.0
+
+### Patch Changes
+
+- Updated dependencies [ac8f029]
+- Updated dependencies [4ab9958]
+  - @objectstack/spec@14.2.0
+  - @objectstack/platform-objects@14.2.0
+  - @objectstack/core@14.2.0
+  - @objectstack/formula@14.2.0
+  - @objectstack/metadata-core@14.2.0
+
+## 14.1.0
+
+### Minor Changes
+
+- 5a8465f: SLA escalation `escalateTo` is position-first (ADR-0090 D3 follow-up to the `position` approver type).
+
+  - **spec**: `ApprovalEscalationSchema.escalateTo` is documented as a position machine name or a
+    specific user id (was "User id, role, or manager level" — the same pre-D3 'role' trap the
+    `position` approver type fixed); the Studio xRef picker kind moves `role` → `position`.
+  - **plugin-approvals**: on escalation, `escalateTo` now expands position holders via
+    `sys_user_position` ∪ the `sys_member.role` transition source (ADR-0057 D4) for both the
+    `reassign` approver hand-off and the `notify` audience. An empty expansion falls back to
+    treating the value as a literal user id, so configs naming a specific user keep working
+    unchanged. The audit trail keeps the authored target.
+  - **lint**: new `approval-escalation-reassign-no-target` warning — `escalation.action: 'reassign'`
+    with no `escalateTo` silently degrades to a notify at runtime; the fix-it prescribes a position
+    or user id target (or `action: 'notify'`).
+
+### Patch Changes
+
+- Updated dependencies [5a8465f]
+- Updated dependencies [7f8620b]
+- Updated dependencies [82ba3a6]
+  - @objectstack/spec@14.1.0
+  - @objectstack/core@14.1.0
+  - @objectstack/formula@14.1.0
+  - @objectstack/metadata-core@14.1.0
+  - @objectstack/platform-objects@14.1.0
+
+## 14.0.0
+
+### Minor Changes
+
+- 216fa9a: Add a `position` approver type so approvals can route to org positions (ADR-0090 D3 fallout).
+
+  Post ADR-0090 D3 the `role` approver type resolves against the better-auth org-membership
+  tier (`sys_member.role`: `owner`/`admin`/`member`) — it was never a position. Downstream
+  apps that authored `{ type: 'role', value: 'sales_manager' }` silently routed approvals to
+  nobody. Now:
+
+  - **spec**: `ApproverType` gains `'position'` — `value` is the position machine name; the
+    approver expands to its holders via `sys_user_position`. Authoring guidance: keep
+    `type: 'role'` ONLY for membership tiers; for org positions use
+    `{ type: 'position', value: '<position_name>' }` (one-line fix for the mismatch above).
+  - **plugin-approvals**: the engine resolves `position` approvers via `sys_user_position` ∪
+    the `sys_member.role` transition source (same semantics as `PositionGraphService` in
+    plugin-sharing). The `department` approver type is now honored by its spec spelling
+    (previously only the off-spec `business_unit`/`bu` dialect matched).
+  - **lint**: new `validateApprovalApprovers` rule — `approval-role-not-membership-tier`
+    warns when a `role` approver's value is not a membership tier and prescribes the
+    `position` rewrite; `approval-approver-type-unknown` flags off-spec approver types
+    (with a `business_unit` → `department` fix-it). Wired into `os lint`.
+
+### Patch Changes
+
+- Updated dependencies [0a8e685]
+- Updated dependencies [afa8115]
+- Updated dependencies [80f12ca]
+- Updated dependencies [332b711]
+- Updated dependencies [e2fa074]
+- Updated dependencies [23c8668]
+- Updated dependencies [29f017d]
+- Updated dependencies [216fa9a]
+- Updated dependencies [6c22b12]
+- Updated dependencies [d0531c4]
+- Updated dependencies [cff5aac]
+  - @objectstack/spec@14.0.0
+  - @objectstack/platform-objects@14.0.0
+  - @objectstack/core@14.0.0
+  - @objectstack/formula@14.0.0
+  - @objectstack/metadata-core@14.0.0
+
 ## 13.0.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -8460,8 +8460,8 @@ declare const SysApprovalApprover: Omit<{
  * `approve` / `reject` edge.
  *
  * This service owns the durable approval *state* — `sys_approval_request` /
- * `sys_approval_action`, approver resolution (team / department / role /
- * manager graph), and the optional status-field mirror — plus the decision
+ * `sys_approval_action`, approver resolution (team / department / position /
+ * role / manager graph), and the optional status-field mirror — plus the decision
  * API. It does not author processes, submit, or walk multi-step machinery
  * anymore; that orchestration lives on the one automation engine.
  */
@@ -8566,16 +8566,20 @@ declare class ApprovalService implements IApprovalService {
     private loadPendingRow;
     /**
      * Expand the approvers on an Approval node into user IDs by querying the
-     * graph tables for `team:` / `department:` / `role:` / `manager:` approver
-     * types. Falls back to a prefixed literal (`type:value`) when graph lookups
-     * produce nothing — so existing fixtures and flows that rely on substring
-     * matching keep working.
+     * graph tables for `team:` / `department:` / `position:` / `role:` /
+     * `manager:` approver types. Falls back to a prefixed literal
+     * (`type:value`) when graph lookups produce nothing — so existing fixtures
+     * and flows that rely on substring matching keep working.
      *
      * **Graph semantics:**
      *   - `team`       → flat members of `sys_team` (better-auth; no BFS)
      *   - `department` → recursive BFS of `sys_business_unit.parent_business_unit_id`
      *                    → members of every descendant via `sys_business_unit_member`
-     *   - `role`       → users with `sys_member.role = value` in tenant
+     *   - `position`   → holders via `sys_user_position` ∪ `sys_member.role`
+     *                    transition source (ADR-0090 D3 / ADR-0057 D4)
+     *   - `role`       → users with `sys_member.role = value` in tenant — the
+     *                    better-auth MEMBERSHIP TIER (owner/admin/member), not a
+     *                    position; author `position` for org positions
      *   - `manager`    → `sys_user.manager_id` of `record[value] ?? record.owner_id`
      *   - `field`      → literal user id stored in `record[value]`
      *   - `user`       → literal value
@@ -8585,6 +8589,16 @@ declare class ApprovalService implements IApprovalService {
     private expandTeamUsers;
     /** Recursive department — walks `sys_business_unit.parent_business_unit_id`. */
     private expandBusinessUnitUsers;
+    /**
+     * Position holders (ADR-0090 D3): `sys_user_position` is the platform-owned
+     * assignment table, keyed by the position's machine name (ADR-0057 D4),
+     * unioned with the better-auth membership string (`sys_member.role`) as a
+     * transition source — the same semantics as `PositionGraphService` in
+     * `plugin-sharing`, so an approval routes to exactly the users the sharing
+     * engine would expand for the same position.
+     */
+    private expandPositionUsers;
+    /** better-auth org-membership tier (`sys_member.role`) — NOT positions. */
     private expandRoleUsers;
     private lookupManager;
     /** Mirror a request status onto a business-object field, if configured. */

package/dist/index.d.ts

@@ -8460,8 +8460,8 @@ declare const SysApprovalApprover: Omit<{
  * `approve` / `reject` edge.
  *
  * This service owns the durable approval *state* — `sys_approval_request` /
- * `sys_approval_action`, approver resolution (team / department / role /
- * manager graph), and the optional status-field mirror — plus the decision
+ * `sys_approval_action`, approver resolution (team / department / position /
+ * role / manager graph), and the optional status-field mirror — plus the decision
  * API. It does not author processes, submit, or walk multi-step machinery
  * anymore; that orchestration lives on the one automation engine.
  */
@@ -8566,16 +8566,20 @@ declare class ApprovalService implements IApprovalService {
     private loadPendingRow;
     /**
      * Expand the approvers on an Approval node into user IDs by querying the
-     * graph tables for `team:` / `department:` / `role:` / `manager:` approver
-     * types. Falls back to a prefixed literal (`type:value`) when graph lookups
-     * produce nothing — so existing fixtures and flows that rely on substring
-     * matching keep working.
+     * graph tables for `team:` / `department:` / `position:` / `role:` /
+     * `manager:` approver types. Falls back to a prefixed literal
+     * (`type:value`) when graph lookups produce nothing — so existing fixtures
+     * and flows that rely on substring matching keep working.
      *
      * **Graph semantics:**
      *   - `team`       → flat members of `sys_team` (better-auth; no BFS)
      *   - `department` → recursive BFS of `sys_business_unit.parent_business_unit_id`
      *                    → members of every descendant via `sys_business_unit_member`
-     *   - `role`       → users with `sys_member.role = value` in tenant
+     *   - `position`   → holders via `sys_user_position` ∪ `sys_member.role`
+     *                    transition source (ADR-0090 D3 / ADR-0057 D4)
+     *   - `role`       → users with `sys_member.role = value` in tenant — the
+     *                    better-auth MEMBERSHIP TIER (owner/admin/member), not a
+     *                    position; author `position` for org positions
      *   - `manager`    → `sys_user.manager_id` of `record[value] ?? record.owner_id`
      *   - `field`      → literal user id stored in `record[value]`
      *   - `user`       → literal value
@@ -8585,6 +8589,16 @@ declare class ApprovalService implements IApprovalService {
     private expandTeamUsers;
     /** Recursive department — walks `sys_business_unit.parent_business_unit_id`. */
     private expandBusinessUnitUsers;
+    /**
+     * Position holders (ADR-0090 D3): `sys_user_position` is the platform-owned
+     * assignment table, keyed by the position's machine name (ADR-0057 D4),
+     * unioned with the better-auth membership string (`sys_member.role`) as a
+     * transition source — the same semantics as `PositionGraphService` in
+     * `plugin-sharing`, so an approval routes to exactly the users the sharing
+     * engine would expand for the same position.
+     */
+    private expandPositionUsers;
+    /** better-auth org-membership tier (`sys_member.role`) — NOT positions. */
     private expandRoleUsers;
     private lookupManager;
     /** Mirror a request status onto a business-object field, if configured. */

package/dist/index.js

@@ -1152,16 +1152,20 @@ var _ApprovalService = class _ApprovalService {
   }
   /**
    * Expand the approvers on an Approval node into user IDs by querying the
-   * graph tables for `team:` / `department:` / `role:` / `manager:` approver
-   * types. Falls back to a prefixed literal (`type:value`) when graph lookups
-   * produce nothing — so existing fixtures and flows that rely on substring
-   * matching keep working.
+   * graph tables for `team:` / `department:` / `position:` / `role:` /
+   * `manager:` approver types. Falls back to a prefixed literal
+   * (`type:value`) when graph lookups produce nothing — so existing fixtures
+   * and flows that rely on substring matching keep working.
    *
    * **Graph semantics:**
    *   - `team`       → flat members of `sys_team` (better-auth; no BFS)
    *   - `department` → recursive BFS of `sys_business_unit.parent_business_unit_id`
    *                    → members of every descendant via `sys_business_unit_member`
-   *   - `role`       → users with `sys_member.role = value` in tenant
+   *   - `position`   → holders via `sys_user_position` ∪ `sys_member.role`
+   *                    transition source (ADR-0090 D3 / ADR-0057 D4)
+   *   - `role`       → users with `sys_member.role = value` in tenant — the
+   *                    better-auth MEMBERSHIP TIER (owner/admin/member), not a
+   *                    position; author `position` for org positions
    *   - `manager`    → `sys_user.manager_id` of `record[value] ?? record.owner_id`
    *   - `field`      → literal user id stored in `record[value]`
    *   - `user`       → literal value
@@ -1186,12 +1190,18 @@ var _ApprovalService = class _ApprovalService {
             for (const u of users) out.push(u);
             continue;
           }
-        } else if (a.type === "business_unit" || a.type === "bu") {
+        } else if (a.type === "department" || a.type === "business_unit" || a.type === "bu") {
           const users = await this.expandBusinessUnitUsers(String(a.value), organizationId);
           if (users.length) {
             for (const u of users) out.push(u);
             continue;
           }
+        } else if (a.type === "position") {
+          const users = await this.expandPositionUsers(String(a.value), organizationId);
+          if (users.length) {
+            for (const u of users) out.push(u);
+            continue;
+          }
         } else if (a.type === "role") {
           const users = await this.expandRoleUsers(String(a.value), organizationId);
           if (users.length) {
@@ -1278,6 +1288,36 @@ var _ApprovalService = class _ApprovalService {
     }
     return Array.from(new Set((rows ?? []).map((r) => String(r.user_id ?? "")).filter(Boolean)));
   }
+  /**
+   * Position holders (ADR-0090 D3): `sys_user_position` is the platform-owned
+   * assignment table, keyed by the position's machine name (ADR-0057 D4),
+   * unioned with the better-auth membership string (`sys_member.role`) as a
+   * transition source — the same semantics as `PositionGraphService` in
+   * `plugin-sharing`, so an approval routes to exactly the users the sharing
+   * engine would expand for the same position.
+   */
+  async expandPositionUsers(positionName, organizationId) {
+    if (!positionName) return [];
+    const users = /* @__PURE__ */ new Set();
+    const filter = { position: positionName };
+    if (organizationId) filter.organization_id = organizationId;
+    try {
+      const rows = await this.engine.find("sys_user_position", {
+        filter,
+        fields: ["user_id"],
+        limit: 1e4,
+        context: SYSTEM_CTX
+      });
+      for (const r of rows ?? []) {
+        const uid2 = String(r.user_id ?? "");
+        if (uid2) users.add(uid2);
+      }
+    } catch {
+    }
+    for (const uid2 of await this.expandRoleUsers(positionName, organizationId)) users.add(uid2);
+    return Array.from(users);
+  }
+  /** better-auth org-membership tier (`sys_member.role`) — NOT positions. */
   async expandRoleUsers(roleName, organizationId) {
     if (!roleName) return [];
     const filter = { role: roleName };
@@ -2199,6 +2239,15 @@ var _ApprovalService = class _ApprovalService {
     const escalateTo = typeof esc2.escalateTo === "string" && esc2.escalateTo.trim() ? esc2.escalateTo.trim() : void 0;
     const now = this.clock.now().toISOString();
     const pending = csvSplit(raw.pending_approvers);
+    let escalatees = [];
+    if (escalateTo) {
+      try {
+        escalatees = await this.expandPositionUsers(escalateTo, raw.organization_id ?? null);
+      } catch {
+        escalatees = [];
+      }
+      if (!escalatees.length) escalatees = [escalateTo];
+    }
     await this.engine.insert("sys_approval_action", {
       id: uid("aact"),
       request_id: raw.id,
@@ -2210,16 +2259,16 @@ var _ApprovalService = class _ApprovalService {
       comment: `${action}${escalateTo ? ` \u2192 ${escalateTo}` : ""}`,
       created_at: now
     }, { context: SYSTEM_CTX });
-    if (action === "reassign" && escalateTo) {
+    if (action === "reassign" && escalatees.length) {
       await this.engine.update("sys_approval_request", {
         id: raw.id,
-        pending_approvers: escalateTo,
+        pending_approvers: escalatees.join(","),
         updated_at: now
       }, { context: SYSTEM_CTX });
-      await this.syncApproverIndex(raw.id, [escalateTo], raw.organization_id ?? null, now);
+      await this.syncApproverIndex(raw.id, escalatees, raw.organization_id ?? null, now);
       await this.notify({
         topic: "approval.escalated",
-        audience: [escalateTo],
+        audience: escalatees,
         actorId: SLA_ACTOR_ID,
         source: { object: "sys_approval_request", id: raw.id },
         payload: {
@@ -2237,7 +2286,7 @@ var _ApprovalService = class _ApprovalService {
     } else {
       await this.notify({
         topic: "approval.sla_breached",
-        audience: [...pending, ...escalateTo ? [escalateTo] : []],
+        audience: [...pending, ...escalatees],
         actorId: SLA_ACTOR_ID,
         source: { object: "sys_approval_request", id: raw.id },
         payload: {