@objectstack/plugin-approvals 17.0.0-rc.0 → 17.0.0-rc.1

package/src/sys-approval-action.object.ts

@@ -1,149 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { ObjectSchema, Field } from '@objectstack/spec/data';
-
-/**
- * sys_approval_action — Audit trail row per approval action.
- *
- * Append-only: every `submit`, `approve`, `reject`, `recall`, or
- * `escalate` event lands here. The engine reads back per-step approval
- * rows to evaluate `behavior: 'unanimous'` (all approvers must approve
- * before advancing) versus `first_response` (any single approval
- * advances the step).
- *
- * @namespace sys
- */
-export const SysApprovalAction = ObjectSchema.create({
-  name: 'sys_approval_action',
-  label: 'Approval Action',
-  pluralLabel: 'Approval Actions',
-  icon: 'check-circle',
-  isSystem: true,
-  managedBy: 'append-only',
-  description: 'Append-only audit trail for approval actions',
-  displayNameField: 'id',
-  nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
-  titleFormat: '{action} · {step_name}',
-  highlightFields: ['request_id', 'step_name', 'action', 'actor_id', 'created_at'],
-
-  // ADR-0104 D3 wave 2. `attachments` is a media field, so the files it holds
-  // are OWNED by this row — and the storage service would otherwise authorize
-  // their download by testing whether the caller can READ this row. It cannot:
-  // this table is deliberately closed to ordinary approver positions, so that
-  // test denies the very approver the attachment was filed for. The approvals
-  // service already owns the rule for seeing a decision (visibility of the
-  // parent request, exactly as `listActions` applies it), so it answers.
-  fileAccessDelegate: 'approvals',
-
-  listViews: {
-    recent: {
-      type: 'grid',
-      name: 'recent',
-      label: 'Recent',
-      data: { provider: 'object', object: 'sys_approval_action' },
-      columns: ['created_at', 'request_id', 'step_name', 'action', 'actor_id', 'comment'],
-      sort: [{ field: 'created_at', order: 'desc' }],
-      pagination: { pageSize: 50 },
-      emptyState: { title: 'No approval actions yet', message: 'Actions are logged automatically when approvals progress.' },
-    },
-    by_actor: {
-      type: 'grid',
-      name: 'by_actor',
-      label: 'By Actor',
-      data: { provider: 'object', object: 'sys_approval_action' },
-      columns: ['actor_id', 'created_at', 'request_id', 'step_name', 'action'],
-      sort: [{ field: 'actor_id', order: 'asc' }, { field: 'created_at', order: 'desc' }],
-      grouping: { fields: [{ field: 'actor_id', order: 'asc', collapsed: false }] },
-      pagination: { pageSize: 100 },
-    },
-    all_actions: {
-      type: 'grid',
-      name: 'all_actions',
-      label: 'All',
-      data: { provider: 'object', object: 'sys_approval_action' },
-      columns: ['created_at', 'request_id', 'step_name', 'action', 'actor_id', 'comment'],
-      sort: [{ field: 'created_at', order: 'desc' }],
-      pagination: { pageSize: 100 },
-    },
-  },
-
-  fields: {
-    id: Field.text({ label: 'Action ID', required: true, readonly: true, group: 'System' }),
-
-    organization_id: Field.lookup('sys_organization', {
-      label: 'Organization',
-      required: false,
-      group: 'System',
-      description: 'Tenant that owns this action (mirrors the parent request)',
-    }),
-
-    request_id: Field.lookup('sys_approval_request', {
-      label: 'Request',
-      required: true,
-      group: 'Target',
-    }),
-
-    step_name: Field.text({
-      label: 'Step',
-      required: false,
-      maxLength: 100,
-      description: 'Machine name of the step at the time of the action',
-      group: 'Target',
-    }),
-
-    step_index: Field.number({
-      label: 'Step Index',
-      required: false,
-      group: 'Target',
-    }),
-
-    action: Field.select(
-      // Keep in sync with `ApprovalActionKind` (spec/contracts). reassign /
-      // remind / request_info / comment are thread interactions — they never
-      // move the flow. revise / resubmit (ADR-0044) DO move it: send back for
-      // revision and the later resubmission. ooo_substitute (#1322 M1) is a
-      // system-recorded reroute of an out-of-office approver — no flow movement.
-      ['submit', 'approve', 'reject', 'recall', 'escalate', 'reassign', 'remind', 'request_info', 'comment', 'revise', 'resubmit', 'ooo_substitute'],
-      {
-        label: 'Action',
-        required: true,
-        group: 'Action',
-      },
-    ),
-
-    actor_id: Field.lookup('sys_user', {
-      label: 'Actor',
-      required: false,
-      group: 'Action',
-    }),
-
-    comment: Field.textarea({ label: 'Comment', required: false, group: 'Action' }),
-
-    attachments: Field.file({
-      label: 'Attachments',
-      required: false,
-      multiple: true,
-      group: 'Action',
-      description: 'Files supporting this action — e.g. a signed contract or evidence (#3266).',
-    }),
-
-    created_at: Field.datetime({
-      label: 'Created At',
-      required: true,
-      defaultValue: 'NOW()',
-      readonly: true,
-      group: 'System',
-    }),
-  },
-
-  indexes: [
-    { fields: ['request_id', 'created_at'] },
-    { fields: ['request_id', 'step_index', 'action'] },
-  ],
-
-  enable: {
-    // [ADR-0103] Engine-owned append-only decision log: appended by the approval
-    // engine (SYSTEM_CTX). Reads stay open.
-    apiMethods: ['get', 'list'],
-  },
-});

package/src/sys-approval-approver.object.ts

@@ -1,85 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { ObjectSchema, Field } from '@objectstack/spec/data';
-
-/**
- * sys_approval_approver — Pending-approver index (issue #1745).
- *
- * One row per (request, approver identity) while the request is **pending**.
- * `sys_approval_request.pending_approvers` stays the human-readable source of
- * truth (a CSV column), but CSV substring matching can neither be indexed nor
- * pushed into an engine query — which made "my pending" a post-filter in
- * memory and broke pagination beyond the scan window.
- *
- * This table is that CSV, normalized: the service mirrors every change to
- * `pending_approvers` here (open / decide / recall / send-back / reassign /
- * escalate), and clears the rows when the request leaves `pending`. So the
- * table only ever holds the live work queue — its size tracks the number of
- * open approvals, not the append-only request history.
- *
- * `approver` holds one identity literal exactly as it appears in the CSV:
- * a user id, an email, or a `role:<name>` / `team:<name>` style literal.
- * Equality (or `$in`) on this column is the indexed replacement for the old
- * per-row substring match.
- *
- * @namespace sys
- */
-export const SysApprovalApprover = ObjectSchema.create({
-  name: 'sys_approval_approver',
-  label: 'Approval Approver',
-  pluralLabel: 'Approval Approvers',
-  icon: 'users',
-  isSystem: true,
-  managedBy: 'engine-owned',
-  description: 'Normalized pending-approver rows for indexed inbox queries',
-  displayNameField: 'id',
-  nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
-  titleFormat: '{approver} · {request_id}',
-  highlightFields: ['request_id', 'approver', 'created_at'],
-
-  fields: {
-    id: Field.text({ label: 'Row ID', required: true, readonly: true, group: 'System' }),
-
-    organization_id: Field.lookup('sys_organization', {
-      label: 'Organization',
-      required: false,
-      group: 'System',
-      description: 'Tenant that owns this row (mirrors the parent request)',
-    }),
-
-    request_id: Field.lookup('sys_approval_request', {
-      label: 'Request',
-      required: true,
-      group: 'Target',
-    }),
-
-    approver: Field.text({
-      label: 'Approver',
-      required: true,
-      maxLength: 255,
-      description: 'One pending-approver identity: user id, email, or role:/team: literal',
-      group: 'Target',
-    }),
-
-    created_at: Field.datetime({
-      label: 'Created At',
-      required: true,
-      defaultValue: 'NOW()',
-      readonly: true,
-      group: 'System',
-    }),
-  },
-
-  indexes: [
-    // "My pending" inbox: equality on the identity literal, scoped by tenant.
-    { fields: ['approver', 'organization_id'] },
-    // Sync path: rewrite all rows of one request on each approver-set change.
-    { fields: ['request_id'] },
-  ],
-
-  enable: {
-    // [ADR-0103] Engine-owned: approver rows are rewritten by the approval
-    // engine (SYSTEM_CTX) on each approver-set change, never via generic CRUD.
-    apiMethods: ['get', 'list'],
-  },
-});

package/src/sys-approval-delegation.object.test.ts

@@ -1,42 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * #3026 follow-up — `sys_approval_delegation` must expose the BATCH shape of
- * the write verbs it already grants.
- *
- * The object is `managedBy: 'system'` but opens generic writes deliberately
- * (`userActions: { create, edit, delete }` — an out-of-office rule is authored
- * by its own user through the plain data endpoint), so the ADR-0103 D3
- * reconciliation strips nothing and its boilerplate CRUD-five whitelist reaches
- * the REST gate as authored. Since the #3391 P1 contract made bulk
- * `bulk ∧ derived(child)`, that whitelist — which never named the `bulk`
- * primitive — 405s every batch route while the single-record verbs stay open.
- */
-
-import { describe, expect, it } from 'vitest';
-import { resolveEffectiveApiMethods, isApiOperationAllowed } from '@objectstack/spec/data';
-import { SysApprovalDelegation } from './sys-approval-delegation.object';
-
-describe('sys_approval_delegation — batch exposure (#3026 / #3391 P1 companion)', () => {
-  it('grants the bulk primitive alongside its single-record write verbs', () => {
-    expect(SysApprovalDelegation.enable?.apiMethods).toContain('bulk');
-    for (const verb of ['get', 'list', 'create', 'update', 'delete'] as const) {
-      expect(SysApprovalDelegation.enable?.apiMethods, `must keep ${verb}`).toContain(verb);
-    }
-  });
-
-  it('admits createMany / updateMany / deleteMany and /batch', () => {
-    const eff = resolveEffectiveApiMethods(SysApprovalDelegation.enable);
-    expect(eff.mode).toBe('restricted');
-    for (const child of ['create', 'update', 'delete'] as const) {
-      expect(isApiOperationAllowed(eff, 'bulk', { bulkChild: child }), `batch ${child}`).toBe(true);
-    }
-  });
-
-  it('keeps the whitelist explicit so the ADR-0103 D3 backstop still runs', () => {
-    // `reconcileManagedApiMethods` early-returns on a non-array `apiMethods`.
-    // For a `managedBy` object, deleting the whitelist would silently disable
-    // managed-write stripping — it is not an equivalent refactor.
-    expect(Array.isArray(SysApprovalDelegation.enable?.apiMethods)).toBe(true);
-  });
-});

package/src/sys-approval-delegation.object.ts

@@ -1,142 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { ObjectSchema, Field } from '@objectstack/spec/data';
-
-/**
- * sys_approval_delegation — self-service out-of-office (OOO) delegation (#1322 M1).
- *
- * A standing, self-declared rule: "while I (the delegator) am out between
- * `valid_from` and `valid_until`, route the approver slots that would resolve
- * to me onto my delegate instead." The approval service consults active rows
- * in `ApprovalService.expandApprovers` when resolving an approval node's
- * INDIVIDUALLY-routed approvers (`type: user` / `field` / `manager`) — the
- * delegate becomes a real pending approver and acts under their own identity,
- * so nothing is impersonated and the audit trail stays honest.
- *
- * Modelled as its own object (not a scalar on the better-auth-locked
- * `sys_user`), mirroring the `sys_user_position` delegation precedent
- * (ADR-0091): the validity window is enforced at RESOLUTION time via the
- * shared `isGrantActive` predicate — never by a background job (ADR-0049).
- * The window is half-open `[valid_from, valid_until)` in UTC.
- *
- * Scope note: this is the community-core OOO auto-skip only. Long-term proxy
- * "act-as" access (viewing/acting on another user's full queue under their
- * authority), delegation governance / segregation-of-duties, and org-wide
- * administration of others' delegations are enterprise concerns tracked
- * separately (objectstack-ai/cloud#855), not here.
- *
- * @namespace sys
- */
-export const SysApprovalDelegation = ObjectSchema.create({
-  name: 'sys_approval_delegation',
-  label: 'Approval Delegation',
-  pluralLabel: 'Approval Delegations',
-  icon: 'user-clock',
-  isSystem: true,
-  managedBy: 'system',
-  // [ADR-0103] Admin/user-writable DATA on a platform-defined schema: a user
-  // authors their own out-of-office delegation. Affordance only (matches the
-  // full-CRUD apiMethods below) — RLS/permission sets are the authz; opening it
-  // keeps the system write guard from rejecting the self-service write.
-  userActions: { create: true, edit: true, delete: true },
-  description:
-    'Self-service out-of-office rule: route this user\'s approver slots to a delegate within a time window (#1322 M1).',
-  titleFormat: '{delegator_id} → {delegate_id}',
-  highlightFields: ['delegator_id', 'delegate_id', 'valid_from', 'valid_until'],
-
-  listViews: {
-    active: {
-      type: 'grid',
-      name: 'active',
-      label: 'Active',
-      data: { provider: 'object', object: 'sys_approval_delegation' },
-      columns: ['delegator_id', 'delegate_id', 'valid_from', 'valid_until', 'reason'],
-      sort: [{ field: 'valid_until', order: 'asc' }],
-      pagination: { pageSize: 50 },
-      emptyState: {
-        title: 'No delegations',
-        message: 'Declare an out-of-office delegation so approvals route to a backup while you are away.',
-      },
-    },
-  },
-
-  fields: {
-    id: Field.text({ label: 'Delegation ID', required: true, readonly: true, group: 'System' }),
-
-    delegator_id: Field.lookup('sys_user', {
-      label: 'Delegator',
-      required: true,
-      group: 'Delegation',
-      description: 'The user going out of office; their individually-routed approver slots are rerouted while active.',
-    }),
-
-    delegate_id: Field.lookup('sys_user', {
-      label: 'Delegate',
-      required: true,
-      group: 'Delegation',
-      description: 'The backup who receives the delegator\'s approvals while this rule is active. Acts under their own identity.',
-    }),
-
-    valid_from: Field.datetime({
-      label: 'Valid From',
-      required: false,
-      group: 'Delegation',
-      description:
-        'Rule is inactive before this instant. Null = active immediately. ' +
-        'Enforced at resolution time via isGrantActive (ADR-0091 D2 predicate) — never by a background job.',
-    }),
-
-    valid_until: Field.datetime({
-      label: 'Valid Until',
-      required: false,
-      group: 'Delegation',
-      description:
-        'Rule is inactive AT and AFTER this instant (half-open [from, until), UTC). Null = never expires.',
-    }),
-
-    reason: Field.text({
-      label: 'Reason',
-      required: false,
-      maxLength: 500,
-      group: 'Delegation',
-      description: 'Why the delegation exists (e.g. "Annual leave 5/26–5/30"). Recorded on the substitution audit row.',
-    }),
-
-    organization_id: Field.lookup('sys_organization', {
-      label: 'Organization',
-      required: false,
-      group: 'System',
-      description: 'Tenant that owns this rule; null = applies across tenants for this delegator.',
-    }),
-
-    created_at: Field.datetime({
-      label: 'Created At',
-      defaultValue: 'NOW()',
-      readonly: true,
-      group: 'System',
-    }),
-
-    updated_at: Field.datetime({
-      label: 'Updated At',
-      defaultValue: 'NOW()',
-      readonly: true,
-      group: 'System',
-    }),
-  },
-
-  indexes: [
-    // Resolution-time lookup: "active delegations for this delegator".
-    { fields: ['delegator_id', 'organization_id'] },
-    { fields: ['delegate_id'] },
-    { fields: ['valid_until'] },
-  ],
-
-  enable: {
-    trackHistory: true,
-    searchable: true,
-    apiEnabled: true,
-    // `bulk` = the batch shape of the verbs above; the gate is `bulk ∧ child`
-    // (#3391 P1), so omitting it 405s /batch and the *Many routes (#3026).
-    apiMethods: ['get', 'list', 'create', 'update', 'delete', 'bulk'],
-  },
-});

package/src/sys-approval-request.object.test.ts

@@ -1,116 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Contract test for the server-declared decision actions on
- * `sys_approval_request` (objectui#2678 P2-4 / retire-hardcoded-buttons).
- *
- * The console's generic action runtime renders + executes these wherever the
- * object is surfaced (the approvals inbox included), so the inbox no longer
- * hand-writes a button per capability. That only holds if the declared set
- * stays faithful to the REST routes it targets and to the who-can-act gating.
- * This pins both:
- *
- *   • every `type:'api'` target resolves `{id}` and points at a route that the
- *     REST server actually registers (approve/reject/reassign/recall/remind/
- *     request-info/revise/resubmit) — a typo'd verb would 404 silently in the UI;
- *   • submitter-only levers (remind/recall/resubmit) gate on
- *     `submitter_id == ctx.user.id` so a non-submitter never sees them.
- */
-
-import { describe, it, expect } from 'vitest';
-import { SysApprovalRequest } from './sys-approval-request.object.js';
-
-const actions = (SysApprovalRequest as any).actions as any[];
-const byName = (n: string) => actions.find((a) => a.name === n);
-/** `ObjectSchema.create` normalizes `visible` strings into a
- *  `{ dialect: 'cel', source }` envelope — read the source for substring asserts. */
-const vis = (n: string): string => {
-  const v = byName(n).visible;
-  return typeof v === 'string' ? v : String(v?.source ?? '');
-};
-
-/** Verbs the REST server registers under `/api/v1/approvals/requests/:id/*`. */
-const ROUTE_VERBS = new Set([
-  'approve', 'reject', 'reassign', 'recall', 'remind', 'request-info', 'revise', 'resubmit',
-]);
-
-describe('sys_approval_request declared actions', () => {
-  it('declares the full decision + continuity set', () => {
-    expect(actions.map((a) => a.name).sort()).toEqual(
-      [
-        'approval_approve',
-        'approval_recall',
-        'approval_reassign',
-        'approval_reject',
-        'approval_remind',
-        'approval_request_info',
-        'approval_resubmit',
-        'approval_send_back',
-      ].sort(),
-    );
-  });
-
-  it('every api target points at a registered approvals route verb and injects {id}', () => {
-    for (const a of actions) {
-      expect(a.type).toBe('api');
-      expect(a.method).toBe('POST');
-      const m = /^\/api\/v1\/approvals\/requests\/\{id\}\/([a-z-]+)$/.exec(a.target);
-      expect(m, `${a.name} target ${a.target}`).not.toBeNull();
-      expect(ROUTE_VERBS.has(m![1]), `${a.name} → ${m![1]}`).toBe(true);
-      expect(a.refreshAfter).toBe(true);
-    }
-  });
-
-  it('gates on the server-computed viewer block (#3310): approver actions on can_act, submitter levers on is_submitter', () => {
-    for (const name of ['approval_remind', 'approval_recall', 'approval_resubmit']) {
-      expect(vis(name)).toContain('record.viewer.is_submitter');
-      expect(vis(name)).not.toContain('can_act');
-    }
-    for (const name of ['approval_approve', 'approval_reject', 'approval_send_back', 'approval_request_info', 'approval_reassign']) {
-      expect(vis(name)).toContain('record.viewer.can_act');
-      // who-can-act is server-derived, never a client identity guess
-      expect(vis(name)).not.toContain('ctx.user.id');
-      expect(vis(name)).not.toContain('is_submitter');
-    }
-  });
-
-  it('the core decision levers OR in the admin override (#3424) so a stuck request is recoverable', () => {
-    // approve / reject / reassign additionally show for a platform/tenant admin
-    // (`record.viewer.can_override`) so an approval routed to an unstaffed
-    // position — otherwise undecidable, locking the record forever — can be
-    // rescued in-product. The secondary approver levers stay slot-only.
-    for (const name of ['approval_approve', 'approval_reject', 'approval_reassign']) {
-      expect(vis(name)).toContain('record.viewer.can_override');
-    }
-    for (const name of ['approval_send_back', 'approval_request_info']) {
-      expect(vis(name)).not.toContain('can_override');
-    }
-  });
-
-  it('recall stays available while a returned request is still the submitter\'s to abandon', () => {
-    expect(vis('approval_recall')).toContain('record.status == "returned"');
-    expect(byName('approval_recall').confirmText).toBeTruthy();
-  });
-
-  it('reassign collects the new approver via a field-backed sys_user picker keyed as `to`', () => {
-    const toParam = byName('approval_reassign').params.find((p: any) => p.name === 'to');
-    expect(toParam).toMatchObject({ field: 'submitter_id', name: 'to', required: true });
-  });
-
-  it('request-info requires a comment; other params stay optional', () => {
-    const ri = byName('approval_request_info').params.find((p: any) => p.name === 'comment');
-    expect(ri.required).toBe(true);
-    for (const name of ['approval_send_back', 'approval_remind', 'approval_recall', 'approval_resubmit']) {
-      const c = byName(name).params.find((p: any) => p.name === 'comment');
-      expect(c.required ?? false).toBe(false);
-    }
-  });
-
-  it('approve/reject collect optional multi-file decision attachments', () => {
-    for (const name of ['approval_approve', 'approval_reject']) {
-      const att = byName(name).params.find((p: any) => p.name === 'attachments');
-      expect(att, `${name}.attachments`).toMatchObject({ type: 'file', multiple: true });
-      expect(att.required ?? false).toBe(false);
-    }
-  });
-});