@dotbep/core 0.2.7 → 0.2.8

package/src/runtime/types.ts

@@ -1,279 +0,0 @@
-// Runtime types for dotBEP workflow engine.
-// These are separate from the BEP schema (bep.json) — instances live outside
-// the plan file and represent the live execution state of each workflow.
-
-// ─── Status ───────────────────────────────────────────────────────────────────
-
-export type InstanceStatus = 'active' | 'completed' | 'suspended' | 'error'
-
-// ─── Incoming event ───────────────────────────────────────────────────────────
-
-/** What a software or user emits to trigger a transition. */
-export interface IncomingEvent {
-  /** ref FlowEvent.id */
-  eventId: string
-  /** ref Software.id — identifies which software is emitting. */
-  softwareId?: string
-  /** Member.email of the person or system acting. */
-  actor: string
-  /** Key-value payload validated against FlowEvent.payload definition. */
-  payload?: Record<string, unknown>
-}
-
-// ─── Transition log ───────────────────────────────────────────────────────────
-
-/** Immutable log entry written after each successful transition. */
-export interface TransitionEvent {
-  id: string
-  /** ref FlowEdge key */
-  edgeId: string
-  fromNodeId: string
-  toNodeId: string
-  /** The event that triggered this transition. */
-  trigger: IncomingEvent
-  /** Member.email */
-  actor: string
-  /** ISO 8601 datetime */
-  timestamp: string
-  /**
-   * True when this transition was performed automatically by the engine
-   * (e.g. decision node auto-traversal). The actor and trigger fields still
-   * reflect the event that caused the automation, not a human action.
-   */
-  auto?: boolean
-  notes?: string
-}
-
-// ─── Workflow instance ────────────────────────────────────────────────────────
-
-export interface WorkflowInstance {
-  id: string
-  /** ref Workflow.id */
-  workflowId: string
-  /** BEP version at the time this instance was created — used to load the correct workflow definition. */
-  bepVersion: string
-
-  /** The asset this instance is tracking. */
-  trackedAsset: {
-    /** ref AssetType.id */
-    assetTypeId: string
-    /**
-     * Namespace that identifies where the asset lives.
-     * Format: "bep:<entityName>" for BEP-internal entities (e.g. "bep:deliverables"),
-     * or "external:<softwareId>" for assets in external systems (e.g. "external:software-acc").
-     * The softwareId must match a Software.id declared in the BEP (which cannot contain colons).
-     */
-    source: string
-    /** ID of the asset — ref to the entity within the source. */
-    id: string
-    label: string
-  }
-
-  /** Key of the current FlowNode. Not a decision node — engine auto-traverses those. */
-  currentNodeId: string
-  status: InstanceStatus
-  /** Ordered log of all transitions, oldest first. */
-  history: TransitionEvent[]
-
-  /** Set when this instance was spawned by a parent instance. */
-  parentInstanceId?: string
-  /** FlowNode key in the parent workflow that spawned this instance. */
-  parentNodeId?: string
-
-  /** ISO 8601 datetime */
-  createdAt: string
-  /** ISO 8601 datetime */
-  updatedAt: string
-  /** Member.email */
-  initiatedBy: string
-}
-
-// ─── Instance filter ──────────────────────────────────────────────────────────
-
-export interface InstanceFilter {
-  /** ref Workflow.id */
-  workflowId?: string
-  status?: InstanceStatus
-  /** Member.email — returns instances where this actor has a pending RACI action. */
-  pendingActionFor?: string
-  /** ref AssetType.id */
-  trackedAssetTypeId?: string
-  /** ID of the asset in the external system. */
-  trackedAssetId?: string
-}
-
-// ─── Node config ──────────────────────────────────────────────────────────────
-
-/** Role reference with minimal resolved fields. */
-export interface RoleRef {
-  id: string
-  name: string
-}
-
-/** Team reference with minimal resolved fields. */
-export interface TeamRef {
-  id: string
-  name: string
-}
-
-/**
- * Resolved RACI assignment for one letter (R/A/C/I) at a node.
- * Three levels of specificity: emails > teams+roles > roles.
- */
-export interface RaciLevel {
-  roles:   RoleRef[]
-  teams:   TeamRef[]
-  /** Explicit member emails authorized regardless of role or team. */
-  emails:  string[]
-}
-
-/** Describes what a specific actor can do from the current node of an instance. */
-export interface NodeConfig {
-  currentNode: {
-    id: string
-    type: string
-    label: string
-  }
-
-  /** Transitions this actor can trigger right now. */
-  availableTransitions: {
-    edgeId: string
-    label: string
-    /** eventId to emit */
-    emits: string
-    requiredPayload: { key: string; type: string; required: boolean }[]
-  }[]
-
-  /** Transitions that exist but this actor cannot trigger. */
-  blockedTransitions: {
-    edgeId: string
-    label: string
-    reason: 'UNAUTHORIZED' | 'GUARD_UNSATISFIABLE'
-    /** What the node requires to authorize this transition. */
-    required: RaciLevel
-  }[]
-
-  /** RACI assignment for the current node — resolved to roles, teams and emails. */
-  raci: {
-    responsible: RaciLevel
-    accountable:  RaciLevel
-    consulted:    RaciLevel
-    informed:     RaciLevel
-  }
-
-  /** True if the current node is type "end". */
-  isTerminal: boolean
-}
-
-// ─── Engine result types ──────────────────────────────────────────────────────
-
-export type ProcessEventError =
-  | 'INSTANCE_NOT_ACTIVE'
-  | 'NO_MATCHING_EDGE'
-  | 'AMBIGUOUS_TRANSITION'
-  | 'DECISION_LOOP'
-  | 'UNAUTHORIZED'
-  | 'INVALID_PAYLOAD'
-
-export interface PayloadFieldError {
-  field: string
-  reason: 'missing' | 'wrong_type' | 'unknown_field'
-}
-
-export interface TransitionStep {
-  edgeId: string
-  fromNodeId: string
-  toNodeId: string
-}
-
-// ─── Effect execution ─────────────────────────────────────────────────────────
-
-/**
- * Handler registered for a specific effectId.
- * Receives the instance and the payload filtered to the keys defined
- * in FlowEffect.payload (resolved from instance.context).
- */
-export type EffectHandler = (
-  instance: WorkflowInstance,
-  payload: Record<string, unknown>,
-) => Promise<void>
-
-/**
- * Handler registered for a specific Resolver.id.
- * Fetches and transforms data from an external source, returning a raw payload
- * for the lens to render. Never handles authentication tokens directly —
- * credentials are passed via env.
- */
-export type ResolverHandler = (
-  url: string,
-  env: Record<string, string>,
-) => Promise<unknown>
-
-/**
- * Handler registered for a specific Adapter.id.
- * Receives the raw output of a resolver and returns a transformed payload
- * compatible with the target lens input schema.
- */
-export type AdapterHandler = (data: unknown) => unknown
-
-/**
- * Handler for an automation node. Receives the instance and the payload filtered
- * from instance.context according to FlowAutomation.payload. Must return an object
- * with an eventId matching the FlowEvent declared on the outgoing edge, plus any
- * additional payload fields used by guards.
- */
-export type AutomationHandler = (
-  instance: WorkflowInstance,
-  payload:  Record<string, unknown>,
-) => Promise<{ eventId: string } & Record<string, unknown>>
-
-export interface EffectOutcome {
-  effectId: string
-  fromEdgeId: string
-  /** executed = handler ran ok | skipped = no handler or missing required fields | failed = handler threw */
-  status: 'executed' | 'skipped' | 'failed'
-  /** Required context fields that were missing. Present when status = 'skipped'. */
-  missingFields?: string[]
-  /** Error message thrown by the handler. Present when status = 'failed'. */
-  error?: string
-}
-
-/** Public result returned by Runtime.emit(). */
-export interface EventResult {
-  ok: boolean
-  instance?: WorkflowInstance
-  transitionsApplied?: TransitionStep[]
-  effects?: EffectOutcome[]
-  error?: ProcessEventError
-  /** Present when error = 'INVALID_PAYLOAD'. */
-  payloadErrors?: PayloadFieldError[]
-}
-
-// ─── Lifecycle listeners ──────────────────────────────────────────────────────
-
-/** Fires after every successful emit() — transitions applied and effects executed. */
-export type TransitionListener = (
-  instance: WorkflowInstance,
-  transitionsApplied: TransitionStep[],
-  effects: EffectOutcome[],
-) => Promise<void>
-
-/** Fires after createInstance() persists the new instance. */
-export type LifecycleListener = (instance: WorkflowInstance) => Promise<void>
-
-/** Fires when an effect handler throws or returns status 'failed'. */
-export type EffectFailedListener = (
-  instance: WorkflowInstance,
-  outcome: EffectOutcome,
-) => Promise<void>
-
-// ─── Storage interface ────────────────────────────────────────────────────────
-
-/** Abstraction over where instances are persisted. */
-export interface InstanceStore {
-  listInstances(filter?: InstanceFilter): Promise<WorkflowInstance[]>
-  getInstance(instanceId: string): Promise<WorkflowInstance | null>
-  saveInstance(instance: WorkflowInstance): Promise<void>
-  deleteInstance(instanceId: string): Promise<void>
-}
-

package/src/types/history.ts

@@ -1,37 +0,0 @@
-import type { BEPVersion } from './schema.js'
-
-export type SectionDiff = { added: string[]; removed: string[]; modified: string[] }
-
-export type BepDiff = {
-  /** Changed fields in bep.project, or null if the project object is unchanged. */
-  project: { changed: true; fields: string[] } | null
-  /** Per-entity diff (only entities with at least one change are included). */
-  sections: Record<string, SectionDiff>
-  /** Top-level keys that changed — 'project' + entity array keys with changes. */
-  changedKeys: string[]
-}
-
-export type StandardChange = {
-  id: string
-  name: string
-  status: 'added' | 'removed' | 'modified' | 'content-modified'
-}
-
-export type BepStatus = BepDiff & {
-  hasPendingChanges: boolean
-  standards: StandardChange[]
-}
-
-// Omit doesn't distribute over unions in TypeScript — DistributiveOmit does.
-type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
-
-/** Input params for commit — computed fields (version, date, diff) are excluded. */
-export type CommitParams = DistributiveOmit<BEPVersion, 'version' | 'date' | 'diff'>
-
-export type SquashParams = {
-  /** New terminus version — must be X.0 format and greater than current. */
-  newBase: string
-  author: string
-  description: string
-  approvedBy: string[]
-}

package/src/types/index.ts

@@ -1,24 +0,0 @@
-export * from './schema.js'
-export type {
-  RaciAssignment,
-  RaciRow,
-  RaciMatrix,
-  MemberResolved,
-  TeamResolved,
-  MilestoneResolved,
-  LBSNodeResolved,
-  AssetTypeResolved,
-  SoftwareResolved,
-  BIMUseResolved,
-  FlowNodeResolved,
-  FlowDiagramResolved,
-  WorkflowResolved,
-  GuideResolved,
-  ActionResolved,
-  RaciEntry,
-  LOINMilestoneResolved,
-  LOINResolved,
-  DeliverableResolved,
-  NoteResolved,
-} from './resolved.js'
-export type { SectionDiff, BepDiff, BepStatus, StandardChange, CommitParams, SquashParams } from './history.js'

package/src/types/resolved.ts

@@ -1,137 +0,0 @@
-import type {
-  Action, Annex, FlowAutomation, BIMUse, Deliverable, Discipline,
-  AssetType, Extension, Role, Guide, LBSNode,
-  LOD, LOI, LOIN, LOINMilestone, Member, Milestone, Note,
-  Objective, Phase, Software, Team, Workflow, FlowDiagram, NodeType, NodeTimeout,
-} from './schema.js'
-
-// ─── RACI ─────────────────────────────────────────────────────────────────────
-
-export type RaciAssignment = {
-  role: Role
-  members: MemberResolved[]
-  team: TeamResolved | null
-}
-
-export type RaciRow = {
-  workflow: { id: string; name: string }
-  nodeId: string
-  label: string
-  actionId?: string
-  description?: string
-  responsible: RaciAssignment[]
-  accountable: RaciAssignment[]
-  consulted:   RaciAssignment[]
-  informed:    RaciAssignment[]
-}
-
-export type RaciMatrix = {
-  /** All unique roles present across all rows — use as column headers. */
-  roles: Role[]
-  rows: RaciRow[]
-}
-
-export type MemberResolved = Omit<Member, 'roleId'> & {
-  role: Role | null
-  team: { id: string; name: string } | null
-  isRepresentative: boolean
-}
-
-export type TeamResolved = Omit<Team, 'representativeEmail' | 'memberEmails' | 'disciplineIds'> & {
-  representative: MemberResolved | null
-  members: MemberResolved[]
-  disciplines: Discipline[]
-}
-
-export type MilestoneResolved = Omit<Milestone, 'phaseId'> & {
-  phase: Phase | null
-}
-
-export type LBSNodeResolved = Omit<LBSNode, 'lbsNodeIds'> & {
-  isRoot: boolean
-  parent: Pick<LBSNode, 'id' | 'name' | 'type'> | null
-  children: LBSNode[]
-}
-
-export type AssetTypeResolved = Omit<AssetType, 'extensionIds'> & {
-  extensions: Extension[]
-}
-
-export type SoftwareResolved = Omit<Software, 'assetTypeIds'> & {
-  assetTypes: AssetTypeResolved[]
-}
-
-export type BIMUseResolved = Omit<BIMUse, 'objectiveIds' | 'milestoneIds' | 'workflowIds'> & {
-  objectives: Objective[]
-  milestones: MilestoneResolved[]
-  workflows: WorkflowResolved[]
-}
-
-/** Resolved RACI assignment for one letter (R/A/C/I) at a node. */
-export type RaciEntry = {
-  roles:   Role[]
-  teams:   Team[]
-  members: Member[]
-}
-
-export type FlowNodeResolved = {
-  type:        NodeType
-  label?:      string
-  workflowId?: string
-  blocking?:   boolean
-  timeouts?:   NodeTimeout[]
-  action:      Action | null
-  automation:  FlowAutomation | null
-  responsible: RaciEntry
-  accountable: RaciEntry
-  consulted:   RaciEntry
-  informed:    RaciEntry
-}
-
-export type FlowDiagramResolved = Omit<FlowDiagram, 'nodes'> & {
-  nodes: Record<string, FlowNodeResolved>
-}
-
-export type WorkflowResolved = Omit<Workflow, 'diagram'> & {
-  diagram: FlowDiagramResolved
-}
-
-export type GuideResolved = Omit<Guide, 'annexIds'> & {
-  annexes: Annex[]
-}
-
-export type ActionResolved = Omit<Action, 'guideIds' | 'softwareIds'> & {
-  guides: GuideResolved[]
-  softwares: Software[]
-}
-
-export type LOINMilestoneResolved = Omit<LOINMilestone, 'milestoneId' | 'lodId' | 'loiId'> & {
-  milestone: Milestone | null
-  lod: LOD | null
-  loi: LOI | null
-}
-
-export type LOINResolved = Omit<LOIN, 'disciplineId' | 'milestones'> & {
-  discipline: Discipline | null
-  milestones: LOINMilestoneResolved[]
-}
-
-export type DeliverableResolved = Omit<
-  Deliverable,
-  'lbsNodeId' | 'disciplineId' | 'assetTypeId' | 'extensionIds' | 'responsibleId' | 'milestoneId' | 'predecessorId'
-> & {
-  nomenclatureCode: string
-  /** Resolved delivery date: dueDate if set, otherwise the milestone's date. */
-  effectiveDate: string
-  lbsNode: LBSNodeResolved | null
-  discipline: Discipline | null
-  assetType: AssetTypeResolved | null
-  extensions: Extension[]
-  responsible: TeamResolved | null
-  milestone: MilestoneResolved | null
-  predecessor: DeliverableResolved | null
-}
-
-export type NoteResolved = Omit<Note, 'memberEmail'> & {
-  member: MemberResolved | null
-}