@contractspec/example.workflow-system 1.57.0 → 1.59.0

package/dist/browser/instance/instance.event.js

@@ -0,0 +1,164 @@
+// src/instance/instance.event.ts
+import { defineEvent, defineSchemaModel } from "@contractspec/lib.contracts";
+import { ScalarTypeEnum } from "@contractspec/lib.schema";
+var InstanceEventPayload = defineSchemaModel({
+  name: "InstanceEventPayload",
+  description: "Base payload for instance events",
+  fields: {
+    instanceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    workflowId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    workflowKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    referenceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    referenceType: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    triggeredBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var StepTransitionPayload = defineSchemaModel({
+  name: "StepTransitionEventPayload",
+  description: "Payload for step transition events",
+  fields: {
+    instanceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    workflowId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    fromStepKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    toStepKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    action: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    executedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var InstanceCompletedPayload = defineSchemaModel({
+  name: "InstanceCompletedEventPayload",
+  description: "Payload when instance completes",
+  fields: {
+    instanceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    workflowId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    workflowKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    outcome: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    referenceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    referenceType: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    duration: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var InstanceStartedEvent = defineEvent({
+  meta: {
+    key: "workflow.instance.started",
+    version: "1.0.0",
+    description: "A new workflow instance has been started.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "instance", "started"]
+  },
+  payload: InstanceEventPayload
+});
+var StepEnteredEvent = defineEvent({
+  meta: {
+    key: "workflow.step.entered",
+    version: "1.0.0",
+    description: "A workflow instance has entered a new step.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "step", "entered"]
+  },
+  payload: StepTransitionPayload
+});
+var StepExitedEvent = defineEvent({
+  meta: {
+    key: "workflow.step.exited",
+    version: "1.0.0",
+    description: "A workflow instance has exited a step.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "step", "exited"]
+  },
+  payload: StepTransitionPayload
+});
+var InstanceCompletedEvent = defineEvent({
+  meta: {
+    key: "workflow.instance.completed",
+    version: "1.0.0",
+    description: "A workflow instance has completed.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "instance", "completed"]
+  },
+  payload: InstanceCompletedPayload
+});
+var InstanceCancelledEvent = defineEvent({
+  meta: {
+    key: "workflow.instance.cancelled",
+    version: "1.0.0",
+    description: "A workflow instance has been cancelled.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "instance", "cancelled"]
+  },
+  payload: InstanceEventPayload
+});
+var InstancePausedEvent = defineEvent({
+  meta: {
+    key: "workflow.instance.paused",
+    version: "1.0.0",
+    description: "A workflow instance has been paused.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "instance", "paused"]
+  },
+  payload: InstanceEventPayload
+});
+var InstanceResumedEvent = defineEvent({
+  meta: {
+    key: "workflow.instance.resumed",
+    version: "1.0.0",
+    description: "A workflow instance has been resumed.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "instance", "resumed"]
+  },
+  payload: InstanceEventPayload
+});
+var InstanceFailedEvent = defineEvent({
+  meta: {
+    key: "workflow.instance.failed",
+    version: "1.0.0",
+    description: "A workflow instance has failed.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "instance", "failed"]
+  },
+  payload: InstanceEventPayload
+});
+var InstanceTimedOutEvent = defineEvent({
+  meta: {
+    key: "workflow.instance.timedOut",
+    version: "1.0.0",
+    description: "A workflow instance has timed out.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "instance", "timeout"]
+  },
+  payload: InstanceEventPayload
+});
+export {
+  StepExitedEvent,
+  StepEnteredEvent,
+  InstanceTimedOutEvent,
+  InstanceStartedEvent,
+  InstanceResumedEvent,
+  InstancePausedEvent,
+  InstanceFailedEvent,
+  InstanceCompletedEvent,
+  InstanceCancelledEvent
+};

package/dist/browser/instance/instance.handler.js

@@ -0,0 +1,356 @@
+// src/shared/mock-data.ts
+var mockDataStore = {
+  workflows: new Map,
+  steps: new Map,
+  instances: new Map,
+  approvals: new Map,
+  stepExecutions: new Map
+};
+
+// src/state-machine/index.ts
+class BasicStateMachineEngine {
+  canTransition(definition, state, action, context) {
+    if (state.status !== "RUNNING" && state.status !== "WAITING") {
+      return {
+        allowed: false,
+        reason: `Workflow is ${state.status}, cannot transition`
+      };
+    }
+    const currentStep = definition.steps[state.currentStepKey];
+    if (!currentStep) {
+      return {
+        allowed: false,
+        reason: `Step ${state.currentStepKey} not found`
+      };
+    }
+    const transition = currentStep.transitions[action];
+    if (!transition) {
+      return {
+        allowed: false,
+        reason: `Action ${action} not available in step ${state.currentStepKey}`
+      };
+    }
+    if (currentStep.allowedRoles && currentStep.allowedRoles.length > 0) {
+      const hasRole = currentStep.allowedRoles.some((role) => context.userRoles.includes(role));
+      if (!hasRole) {
+        return {
+          allowed: false,
+          reason: `User lacks required role for this action`
+        };
+      }
+    }
+    if (typeof transition === "object" && transition.allowedRoles && transition.allowedRoles.length > 0) {
+      const hasRole = transition.allowedRoles.some((role) => context.userRoles.includes(role));
+      if (!hasRole) {
+        return {
+          allowed: false,
+          reason: `User lacks required role for action ${action}`
+        };
+      }
+    }
+    return { allowed: true };
+  }
+  getAvailableActions(definition, state, context) {
+    if (state.status !== "RUNNING" && state.status !== "WAITING") {
+      return [];
+    }
+    const currentStep = definition.steps[state.currentStepKey];
+    if (!currentStep) {
+      return [];
+    }
+    return Object.keys(currentStep.transitions).filter((action) => {
+      const result = this.canTransition(definition, state, action, context);
+      return result.allowed;
+    });
+  }
+  transition(definition, state, action, context) {
+    const validation = this.canTransition(definition, state, action, context);
+    if (!validation.allowed) {
+      return {
+        success: false,
+        previousStepKey: state.currentStepKey,
+        currentStepKey: state.currentStepKey,
+        status: state.status,
+        error: validation.reason
+      };
+    }
+    const currentStep = definition.steps[state.currentStepKey];
+    if (!currentStep) {
+      return {
+        success: false,
+        previousStepKey: state.currentStepKey,
+        currentStepKey: state.currentStepKey,
+        status: state.status,
+        error: `Current step ${state.currentStepKey} not found`
+      };
+    }
+    const transition = currentStep.transitions[action];
+    if (!transition) {
+      return {
+        success: false,
+        previousStepKey: state.currentStepKey,
+        currentStepKey: state.currentStepKey,
+        status: state.status,
+        error: `Transition for action ${action} not found`
+      };
+    }
+    const targetStepKey = typeof transition === "string" ? transition : transition.targetStepKey;
+    const targetStep = definition.steps[targetStepKey];
+    if (!targetStep) {
+      return {
+        success: false,
+        previousStepKey: state.currentStepKey,
+        currentStepKey: state.currentStepKey,
+        status: state.status,
+        error: `Target step ${targetStepKey} not found`
+      };
+    }
+    let newStatus = "RUNNING";
+    if (targetStep.type === "END") {
+      newStatus = "COMPLETED";
+    } else if (targetStep.type === "APPROVAL" || targetStep.type === "WAIT") {
+      newStatus = "WAITING";
+    }
+    return {
+      success: true,
+      previousStepKey: state.currentStepKey,
+      currentStepKey: targetStepKey,
+      status: newStatus
+    };
+  }
+  evaluateCondition(expression, contextData) {
+    try {
+      const match = expression.match(/^(\w+)\s*(>=|<=|>|<|===|!==|==|!=)\s*(.+)$/);
+      if (match) {
+        const [, prop, operator, value] = match;
+        if (!prop || !operator || value === undefined) {
+          return false;
+        }
+        const propValue = contextData[prop];
+        const compareValue = JSON.parse(value);
+        switch (operator) {
+          case ">":
+            return Number(propValue) > Number(compareValue);
+          case "<":
+            return Number(propValue) < Number(compareValue);
+          case ">=":
+            return Number(propValue) >= Number(compareValue);
+          case "<=":
+            return Number(propValue) <= Number(compareValue);
+          case "===":
+          case "==":
+            return propValue === compareValue;
+          case "!==":
+          case "!=":
+            return propValue !== compareValue;
+        }
+      }
+      if (expression in contextData) {
+        return Boolean(contextData[expression]);
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+}
+function createStateMachineEngine() {
+  return new BasicStateMachineEngine;
+}
+function buildStateMachineDefinition(workflow, steps) {
+  const stepMap = {};
+  for (const step of steps) {
+    stepMap[step.key] = {
+      key: step.key,
+      name: step.name,
+      type: step.type,
+      transitions: step.transitions,
+      approvalMode: step.approvalMode,
+      allowedRoles: step.approverRoles,
+      timeoutSeconds: step.timeoutSeconds,
+      conditionExpression: step.conditionExpression
+    };
+  }
+  const startStep = steps.find((s) => s.type === "START");
+  const initialStepKey = startStep?.key ?? steps[0]?.key ?? "";
+  return {
+    key: workflow.key,
+    name: workflow.name,
+    version: workflow.version,
+    initialStepKey,
+    steps: stepMap
+  };
+}
+function createInitialState(definition, contextData = {}) {
+  return {
+    currentStepKey: definition.initialStepKey,
+    status: "RUNNING",
+    contextData,
+    history: []
+  };
+}
+
+// src/approval/approval.handler.ts
+async function createApprovalRequests(instance, step, _context) {
+  const now = new Date;
+  for (let i = 0;i < step.approverRoles.length; i++) {
+    const role = step.approverRoles[i];
+    const id = `approval_${Date.now()}_${i}`;
+    const request = {
+      id,
+      workflowInstanceId: instance.id,
+      stepExecutionId: `exec_${instance.id}_${step.id}`,
+      approverId: `user_${role}`,
+      approverRole: role,
+      title: `Approval required for ${step.name}`,
+      description: step.description,
+      status: "PENDING",
+      contextSnapshot: instance.contextData,
+      sequenceOrder: i,
+      createdAt: now,
+      updatedAt: now
+    };
+    mockDataStore.approvals.set(id, request);
+  }
+}
+async function handleSubmitDecision(input, context) {
+  const request = mockDataStore.approvals.get(input.requestId);
+  if (!request) {
+    throw new Error(`Approval request ${input.requestId} not found`);
+  }
+  if (request.approverId !== context.userId && !context.userRoles.includes(request.approverRole ?? "")) {
+    throw new Error("User is not authorized to make this decision");
+  }
+  const now = new Date;
+  request.decision = input.decision;
+  request.decisionComment = input.comment;
+  request.decidedAt = now;
+  request.updatedAt = now;
+  if (input.decision === "APPROVE") {
+    request.status = "APPROVED";
+    await handleTransitionWorkflow({
+      instanceId: request.workflowInstanceId,
+      action: "approve",
+      data: input.data,
+      comment: input.comment
+    }, context);
+  } else if (input.decision === "REJECT") {
+    request.status = "REJECTED";
+    await handleTransitionWorkflow({
+      instanceId: request.workflowInstanceId,
+      action: "reject",
+      data: input.data,
+      comment: input.comment
+    }, context);
+  }
+  return request;
+}
+async function handleListMyApprovals(input, context) {
+  let requests = Array.from(mockDataStore.approvals.values()).filter((r) => r.approverId === context.userId || context.userRoles.includes(r.approverRole ?? ""));
+  const pendingCount = requests.filter((r) => r.status === "PENDING").length;
+  if (input.status) {
+    requests = requests.filter((r) => r.status === input.status);
+  }
+  const total = requests.length;
+  const offset = input.offset ?? 0;
+  const limit = input.limit ?? 20;
+  requests = requests.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime()).slice(offset, offset + limit);
+  return { requests, total, pendingCount };
+}
+
+// src/instance/instance.handler.ts
+async function handleStartWorkflow(input, context) {
+  const workflow = Array.from(mockDataStore.workflows.values()).find((w) => w.key === input.workflowKey && w.status === "ACTIVE" && w.organizationId === context.organizationId);
+  if (!workflow) {
+    throw new Error(`Active workflow ${input.workflowKey} not found`);
+  }
+  const id = `inst_${Date.now()}`;
+  const now = new Date;
+  const instance = {
+    id,
+    workflowDefinitionId: workflow.id,
+    referenceId: input.referenceId,
+    referenceType: input.referenceType,
+    status: "RUNNING",
+    currentStepId: workflow.initialStepId,
+    contextData: input.contextData ?? {},
+    triggeredBy: context.userId,
+    organizationId: context.organizationId,
+    priority: input.priority ?? 0,
+    dueAt: input.dueAt,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: now
+  };
+  mockDataStore.instances.set(id, instance);
+  if (workflow.initialStepId) {
+    const firstStep = mockDataStore.steps.get(workflow.initialStepId);
+    if (firstStep?.type === "APPROVAL") {
+      instance.status = "WAITING";
+      await createApprovalRequests(instance, firstStep, context);
+    }
+  }
+  return instance;
+}
+async function handleTransitionWorkflow(input, context) {
+  const instance = mockDataStore.instances.get(input.instanceId);
+  if (!instance) {
+    throw new Error(`Instance ${input.instanceId} not found`);
+  }
+  const workflow = mockDataStore.workflows.get(instance.workflowDefinitionId);
+  if (!workflow) {
+    throw new Error(`Workflow ${instance.workflowDefinitionId} not found`);
+  }
+  const steps = Array.from(mockDataStore.steps.values()).filter((s) => s.workflowDefinitionId === workflow.id);
+  const definition = buildStateMachineDefinition({
+    key: workflow.key,
+    name: workflow.name,
+    version: workflow.version,
+    initialStepId: workflow.initialStepId ?? null
+  }, steps);
+  const currentStep = steps.find((s) => s.id === instance.currentStepId);
+  const state = {
+    currentStepKey: currentStep?.key ?? "",
+    status: instance.status,
+    contextData: instance.contextData,
+    history: []
+  };
+  const transitionContext = {
+    userId: context.userId,
+    userRoles: context.userRoles,
+    data: input.data
+  };
+  const engine = createStateMachineEngine();
+  const result = engine.transition(definition, state, input.action, transitionContext);
+  if (!result.success) {
+    return {
+      success: false,
+      instance,
+      message: result.error
+    };
+  }
+  const previousStepKey = currentStep?.key;
+  const newStep = steps.find((s) => s.key === result.currentStepKey);
+  instance.currentStepId = newStep?.id;
+  instance.status = result.status;
+  instance.contextData = { ...instance.contextData, ...input.data };
+  instance.updatedAt = new Date;
+  if (result.status === "COMPLETED") {
+    instance.completedAt = new Date;
+    instance.outcome = input.action;
+  }
+  if (newStep?.type === "APPROVAL") {
+    instance.status = "WAITING";
+    await createApprovalRequests(instance, newStep, context);
+  }
+  return {
+    success: true,
+    instance,
+    previousStepKey,
+    currentStepKey: result.currentStepKey ?? undefined
+  };
+}
+export {
+  handleTransitionWorkflow,
+  handleStartWorkflow
+};

package/dist/browser/instance/instance.operations.js

@@ -0,0 +1,9 @@
+export {
+  TransitionWorkflowContract,
+  StartWorkflowContract,
+  ResumeWorkflowContract,
+  PauseWorkflowContract,
+  ListInstancesContract,
+  GetInstanceContract,
+  CancelWorkflowContract
+};

package/dist/browser/instance/instance.schema.js

@@ -0,0 +1,101 @@
+// src/instance/instance.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var InstanceStatusEnum = defineEnum("InstanceStatus", [
+  "PENDING",
+  "RUNNING",
+  "WAITING",
+  "PAUSED",
+  "COMPLETED",
+  "CANCELLED",
+  "FAILED",
+  "TIMEOUT"
+]);
+
+// src/instance/instance.schema.ts
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var WorkflowInstanceModel = defineSchemaModel({
+  name: "WorkflowInstanceModel",
+  description: "A running workflow instance",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    workflowDefinitionId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    referenceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    referenceType: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    status: { type: InstanceStatusEnum, isOptional: false },
+    currentStepId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    contextData: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    triggeredBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    priority: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    dueAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    outcome: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    resultData: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    errorMessage: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    startedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var StartWorkflowInputModel = defineSchemaModel({
+  name: "StartWorkflowInput",
+  description: "Input for starting a workflow",
+  fields: {
+    workflowKey: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    contextData: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    referenceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    referenceType: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    priority: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    dueAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var TransitionInputModel = defineSchemaModel({
+  name: "TransitionInput",
+  description: "Input for transitioning a workflow",
+  fields: {
+    instanceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    action: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    data: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    comment: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var TransitionResultModel = defineSchemaModel({
+  name: "TransitionResult",
+  description: "Result of a workflow transition",
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    instance: { type: WorkflowInstanceModel, isOptional: false },
+    previousStepKey: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    currentStepKey: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    message: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+export {
+  WorkflowInstanceModel,
+  TransitionResultModel,
+  TransitionInputModel,
+  StartWorkflowInputModel
+};