@objectstack/plugin-approvals 7.3.0 → 7.4.0

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

@@ -0,0 +1,120 @@
+// 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',
+  titleFormat: '{action} · {step_name}',
+  compactLayout: ['request_id', 'step_name', 'action', 'actor_id', 'created_at'],
+
+  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(
+      ['submit', 'approve', 'reject', 'recall', 'escalate'],
+      {
+        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' }),
+
+    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'] },
+  ],
+});

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

@@ -0,0 +1,227 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * sys_approval_request — Live approval instance.
+ *
+ * ADR-0019: opened by a flow's **Approval node** when the run reaches it; the
+ * run suspends until a decision is recorded. The row's lifecycle:
+ *
+ *   `pending` → (per-approver decisions) → `approved` | `rejected`
+ *   `pending` → recalled by submitter → `recalled`
+ *
+ * `flow_run_id` / `flow_node_id` tie the request back to the suspended run so a
+ * decision can resume it; `current_step` mirrors the node id. `node_config_json`
+ * snapshots the Approval node config (approvers / behaviour) the request was
+ * opened with.
+ *
+ * `payload_json` captures a snapshot of the target record at submission
+ * time — used by notifications so they can render before the record is
+ * locked or changed.
+ *
+ * @namespace sys
+ */
+export const SysApprovalRequest = ObjectSchema.create({
+  name: 'sys_approval_request',
+  label: 'Approval Request',
+  pluralLabel: 'Approval Requests',
+  icon: 'inbox',
+  isSystem: true,
+  managedBy: 'system',
+  description: 'Live approval instance tracked per submission',
+  displayNameField: 'id',
+  titleFormat: '{process_name} · {record_id}',
+  compactLayout: ['process_name', 'object_name', 'record_id', 'status', 'current_step', 'submitter_id', 'updated_at'],
+
+  // Curated built-in list views — render as segmented tabs in the console.
+  // Filters use {current_user_id} substitution wired by the console.
+  listViews: {
+    my_pending: {
+      type: 'grid',
+      name: 'my_pending',
+      label: 'My Pending',
+      data: { provider: 'object', object: 'sys_approval_request' },
+      columns: ['process_name', 'object_name', 'record_id', 'current_step', 'submitter_id', 'updated_at'],
+      filter: [
+        { field: 'status', operator: 'equals', value: 'pending' },
+        { field: 'pending_approvers', operator: 'contains', value: '{current_user_id}' },
+      ],
+      sort: [{ field: 'updated_at', order: 'desc' }],
+      pagination: { pageSize: 25 },
+      emptyState: { title: 'No pending approvals', message: 'You\'re all caught up.' },
+    },
+    submitted_by_me: {
+      type: 'grid',
+      name: 'submitted_by_me',
+      label: 'I Submitted',
+      data: { provider: 'object', object: 'sys_approval_request' },
+      columns: ['process_name', 'object_name', 'record_id', 'status', 'current_step', 'updated_at'],
+      filter: [{ field: 'submitter_id', operator: 'equals', value: '{current_user_id}' }],
+      sort: [{ field: 'updated_at', order: 'desc' }],
+      pagination: { pageSize: 25 },
+    },
+    completed: {
+      type: 'grid',
+      name: 'completed',
+      label: 'Completed',
+      data: { provider: 'object', object: 'sys_approval_request' },
+      columns: ['process_name', 'object_name', 'record_id', 'status', 'submitter_id', 'completed_at'],
+      filter: [{ field: 'status', operator: 'in', value: ['approved', 'rejected', 'recalled'] }],
+      sort: [{ field: 'completed_at', order: 'desc' }],
+      pagination: { pageSize: 25 },
+    },
+    all_requests: {
+      type: 'grid',
+      name: 'all_requests',
+      label: 'All',
+      data: { provider: 'object', object: 'sys_approval_request' },
+      columns: ['process_name', 'object_name', 'record_id', 'status', 'current_step', 'submitter_id', 'updated_at'],
+      sort: [{ field: 'updated_at', order: 'desc' }],
+      pagination: { pageSize: 50 },
+    },
+  },
+
+  fields: {
+    id: Field.text({ label: 'Request ID', required: true, readonly: true, group: 'System' }),
+
+    organization_id: Field.lookup('sys_organization', {
+      label: 'Organization',
+      required: false,
+      group: 'System',
+      description: 'Tenant that owns this approval request (propagated from submitter context)',
+    }),
+
+    process_name: Field.text({
+      label: 'Source',
+      required: true,
+      maxLength: 100,
+      description: 'Origin of the request — `flow:<flowName|nodeId>` for node-driven approvals',
+      group: 'Target',
+    }),
+
+    object_name: Field.text({
+      label: 'Object',
+      required: true,
+      maxLength: 100,
+      group: 'Target',
+    }),
+
+    record_id: Field.text({
+      label: 'Record ID',
+      required: true,
+      maxLength: 100,
+      group: 'Target',
+    }),
+
+    submitter_id: Field.lookup('sys_user', {
+      label: 'Submitter',
+      required: false,
+      group: 'Target',
+    }),
+
+    submitter_comment: Field.textarea({
+      label: 'Submitter Comment',
+      required: false,
+      group: 'Target',
+    }),
+
+    status: Field.select(
+      ['pending', 'approved', 'rejected', 'recalled'],
+      {
+        label: 'Status',
+        required: true,
+        defaultValue: 'pending',
+        description: 'Lifecycle state of the request',
+        group: 'State',
+      },
+    ),
+
+    current_step: Field.text({
+      label: 'Current Step',
+      required: false,
+      maxLength: 100,
+      description: 'Machine name of the step awaiting approval',
+      group: 'State',
+    }),
+
+    current_step_index: Field.number({
+      label: 'Current Step Index',
+      required: false,
+      defaultValue: 0,
+      group: 'State',
+    }),
+
+    pending_approvers: Field.textarea({
+      label: 'Pending Approvers',
+      required: false,
+      description: 'Comma-separated user ids who can act on the current step',
+      group: 'State',
+    }),
+
+    payload_json: Field.textarea({
+      label: 'Snapshot',
+      required: false,
+      description: 'Record snapshot at submission time',
+      group: 'State',
+    }),
+
+    // ── ADR-0019: approval-as-flow-node correlation ──────────────────
+    // When a request is opened by an Approval *node* (rather than a standalone
+    // process), these tie it back to the suspended flow run so a decision can
+    // resume it. Null for legacy process-driven requests.
+    flow_run_id: Field.text({
+      label: 'Flow Run',
+      required: false,
+      maxLength: 100,
+      readonly: true,
+      description: 'Suspended automation run id this request gates (ADR-0019). The decision resumes it.',
+      group: 'State',
+    }),
+
+    flow_node_id: Field.text({
+      label: 'Flow Node',
+      required: false,
+      maxLength: 100,
+      readonly: true,
+      description: 'Approval node id within the flow that opened this request (ADR-0019).',
+      group: 'State',
+    }),
+
+    node_config_json: Field.textarea({
+      label: 'Node Config',
+      required: false,
+      readonly: true,
+      description: 'Snapshot of the Approval node config (approvers/behavior) for node-driven requests (ADR-0019).',
+      group: 'State',
+    }),
+
+    completed_at: Field.datetime({
+      label: 'Completed At',
+      required: false,
+      group: 'State',
+    }),
+
+    created_at: Field.datetime({
+      label: 'Created At',
+      required: true,
+      defaultValue: 'NOW()',
+      readonly: true,
+      group: 'System',
+    }),
+
+    updated_at: Field.datetime({ label: 'Updated At', required: false, group: 'System' }),
+  },
+
+  indexes: [
+    // Look up "is there a pending request for this record?" — common
+    // guard on submit and on edit-while-locked checks.
+    { fields: ['object_name', 'record_id'] },
+    { fields: ['status', 'object_name'] },
+    // "My approvals" inbox — pending_approvers is a CSV string so this
+    // index only helps with status pre-filtering; the engine does a
+    // post-filter substring match per row.
+    { fields: ['status', 'updated_at'] },
+    { fields: ['submitter_id', 'status'] },
+  ],
+});

package/src/translations/en.objects.generated.ts

@@ -0,0 +1,156 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Auto-generated by 'os i18n extract' for locale 'en'.
+ * Edit translations in place; re-run extract (with --merge) to fill new gaps.
+ * Do not hand-edit the structure — only the leaf string values.
+ */
+
+import type { TranslationData } from '@objectstack/spec/system';
+
+export const enObjects: NonNullable<TranslationData['objects']> = {
+  sys_approval_request: {
+    label: "Approval Request",
+    pluralLabel: "Approval Requests",
+    description: "Live approval instance tracked per submission",
+    fields: {
+      id: {
+        label: "Request ID"
+      },
+      organization_id: {
+        label: "Organization",
+        help: "Tenant that owns this approval request (propagated from submitter context)"
+      },
+      process_name: {
+        label: "Source",
+        help: "Origin of the request — `flow:<flowName|nodeId>` for node-driven approvals"
+      },
+      object_name: {
+        label: "Object"
+      },
+      record_id: {
+        label: "Record ID"
+      },
+      submitter_id: {
+        label: "Submitter"
+      },
+      submitter_comment: {
+        label: "Submitter Comment"
+      },
+      status: {
+        label: "Status",
+        help: "Lifecycle state of the request",
+        options: {
+          pending: "pending",
+          approved: "approved",
+          rejected: "rejected",
+          recalled: "recalled"
+        }
+      },
+      current_step: {
+        label: "Current Step",
+        help: "Machine name of the step awaiting approval"
+      },
+      current_step_index: {
+        label: "Current Step Index"
+      },
+      pending_approvers: {
+        label: "Pending Approvers",
+        help: "Comma-separated user ids who can act on the current step"
+      },
+      payload_json: {
+        label: "Snapshot",
+        help: "Record snapshot at submission time"
+      },
+      flow_run_id: {
+        label: "Flow Run",
+        help: "Suspended automation run id this request gates (ADR-0019). The decision resumes it."
+      },
+      flow_node_id: {
+        label: "Flow Node",
+        help: "Approval node id within the flow that opened this request (ADR-0019)."
+      },
+      node_config_json: {
+        label: "Node Config",
+        help: "Snapshot of the Approval node config (approvers/behavior) for node-driven requests (ADR-0019)."
+      },
+      completed_at: {
+        label: "Completed At"
+      },
+      created_at: {
+        label: "Created At"
+      },
+      updated_at: {
+        label: "Updated At"
+      }
+    },
+    _views: {
+      my_pending: {
+        label: "My Pending"
+      },
+      submitted_by_me: {
+        label: "I Submitted"
+      },
+      completed: {
+        label: "Completed"
+      },
+      all_requests: {
+        label: "All"
+      }
+    }
+  },
+  sys_approval_action: {
+    label: "Approval Action",
+    pluralLabel: "Approval Actions",
+    description: "Append-only audit trail for approval actions",
+    fields: {
+      id: {
+        label: "Action ID"
+      },
+      organization_id: {
+        label: "Organization",
+        help: "Tenant that owns this action (mirrors the parent request)"
+      },
+      request_id: {
+        label: "Request"
+      },
+      step_name: {
+        label: "Step",
+        help: "Machine name of the step at the time of the action"
+      },
+      step_index: {
+        label: "Step Index"
+      },
+      action: {
+        label: "Action",
+        options: {
+          submit: "submit",
+          approve: "approve",
+          reject: "reject",
+          recall: "recall",
+          escalate: "escalate"
+        }
+      },
+      actor_id: {
+        label: "Actor"
+      },
+      comment: {
+        label: "Comment"
+      },
+      created_at: {
+        label: "Created At"
+      }
+    },
+    _views: {
+      recent: {
+        label: "Recent"
+      },
+      by_actor: {
+        label: "By Actor"
+      },
+      all_actions: {
+        label: "All"
+      }
+    }
+  }
+};

package/src/translations/es-ES.objects.generated.ts

@@ -0,0 +1,156 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Auto-generated by 'os i18n extract' for locale 'es-ES'.
+ * Edit translations in place; re-run extract (with --merge) to fill new gaps.
+ * Do not hand-edit the structure — only the leaf string values.
+ */
+
+import type { TranslationData } from '@objectstack/spec/system';
+
+export const esESObjects: NonNullable<TranslationData['objects']> = {
+  sys_approval_request: {
+    label: "Solicitud de aprobación",
+    pluralLabel: "Solicitudes de aprobación",
+    description: "Instancia activa de aprobación registrada por envío",
+    fields: {
+      id: {
+        label: "ID de solicitud"
+      },
+      organization_id: {
+        label: "Organización",
+        help: "Tenant que posee esta solicitud de aprobación (propagado desde el contexto del solicitante)."
+      },
+      process_name: {
+        label: "Origen",
+        help: "Origen de la solicitud — `flow:<flowName|nodeId>` para aprobaciones por nodo"
+      },
+      object_name: {
+        label: "Objeto"
+      },
+      record_id: {
+        label: "ID de registro"
+      },
+      submitter_id: {
+        label: "Solicitante"
+      },
+      submitter_comment: {
+        label: "Comentario del solicitante"
+      },
+      status: {
+        label: "Estado",
+        help: "Estado del ciclo de vida de la solicitud.",
+        options: {
+          pending: "Pendiente",
+          approved: "Aprobada",
+          rejected: "Rechazada",
+          recalled: "Retirada"
+        }
+      },
+      current_step: {
+        label: "Paso actual",
+        help: "Nombre técnico del paso pendiente de aprobación."
+      },
+      current_step_index: {
+        label: "Índice del paso actual"
+      },
+      pending_approvers: {
+        label: "Aprobadores pendientes",
+        help: "ID de usuario separados por comas que pueden actuar en el paso actual."
+      },
+      payload_json: {
+        label: "Instantánea",
+        help: "Instantánea del registro en el momento del envío."
+      },
+      flow_run_id: {
+        label: "Flow Run",
+        help: "Suspended automation run id this request gates (ADR-0019). The decision resumes it."
+      },
+      flow_node_id: {
+        label: "Flow Node",
+        help: "Approval node id within the flow that opened this request (ADR-0019)."
+      },
+      node_config_json: {
+        label: "Node Config",
+        help: "Snapshot of the Approval node config (approvers/behavior) for node-driven requests (ADR-0019)."
+      },
+      completed_at: {
+        label: "Completado el"
+      },
+      created_at: {
+        label: "Creado el"
+      },
+      updated_at: {
+        label: "Actualizado el"
+      }
+    },
+    _views: {
+      my_pending: {
+        label: "Mis pendientes"
+      },
+      submitted_by_me: {
+        label: "Enviadas por mí"
+      },
+      completed: {
+        label: "Completadas"
+      },
+      all_requests: {
+        label: "Todas"
+      }
+    }
+  },
+  sys_approval_action: {
+    label: "Acción de aprobación",
+    pluralLabel: "Acciones de aprobación",
+    description: "Registro de auditoría append-only para acciones de aprobación",
+    fields: {
+      id: {
+        label: "ID de acción"
+      },
+      organization_id: {
+        label: "Organización",
+        help: "Tenant que posee esta acción (refleja la solicitud principal)."
+      },
+      request_id: {
+        label: "Solicitud"
+      },
+      step_name: {
+        label: "Paso",
+        help: "Nombre técnico del paso en el momento de la acción."
+      },
+      step_index: {
+        label: "Índice del paso"
+      },
+      action: {
+        label: "Acción",
+        options: {
+          submit: "Enviar",
+          approve: "Aprobar",
+          reject: "Rechazar",
+          recall: "Retirar",
+          escalate: "Escalar"
+        }
+      },
+      actor_id: {
+        label: "Actor"
+      },
+      comment: {
+        label: "Comentario"
+      },
+      created_at: {
+        label: "Creado el"
+      }
+    },
+    _views: {
+      recent: {
+        label: "Recientes"
+      },
+      by_actor: {
+        label: "Por actor"
+      },
+      all_actions: {
+        label: "Todas"
+      }
+    }
+  }
+};

package/src/translations/index.ts

@@ -0,0 +1,23 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * ApprovalsTranslations — i18n bundle owned by this plugin (ADR-0029 D8).
+ *
+ * Object label/field/view/action translations for the sys_* objects this
+ * plugin owns. Loaded at runtime via the plugin's `kernel:ready` hook
+ * (`i18n.loadTranslations`). Regenerate with `os i18n extract` against
+ * `scripts/i18n-extract.config.ts`.
+ */
+
+import type { TranslationBundle } from '@objectstack/spec/system';
+import { enObjects } from './en.objects.generated.js';
+import { zhCNObjects } from './zh-CN.objects.generated.js';
+import { jaJPObjects } from './ja-JP.objects.generated.js';
+import { esESObjects } from './es-ES.objects.generated.js';
+
+export const ApprovalsTranslations: TranslationBundle = {
+  en: { objects: enObjects },
+  'zh-CN': { objects: zhCNObjects },
+  'ja-JP': { objects: jaJPObjects },
+  'es-ES': { objects: esESObjects },
+};