@bernierllc/content-editorial-workflow

Configurable editorial workflow engine for content management.

Overview

This package provides a flexible, configurable editorial workflow engine that allows you to define custom content workflows with multiple stages, transitions, and permissions. It's designed to handle complex editorial processes while remaining simple to configure and use.

Features

• Configurable Workflows: Define custom editorial workflows with multiple stages
• Stage Management: Create stages with specific properties (publish, scheduling, permissions)
• Transition Control: Define how content moves between stages
• Permission System: Control who can perform specific actions
• Event System: Listen to workflow events for integration
• Validation: Built-in workflow validation
• Templates: Pre-built workflow templates for common use cases
• TypeScript Support: Full type safety and IntelliSense

Installation

npm install @bernierllc/content-editorial-workflow

Quick Start

import { 
  EditorialWorkflowEngine, 
  WorkflowBuilder, 
  WorkflowTemplates 
} from '@bernierllc/content-editorial-workflow';

// Create a workflow engine
const engine = new EditorialWorkflowEngine();

// Register a workflow
const workflow = WorkflowTemplates.writeAndPublish();
engine.registerWorkflow(workflow);

// Create content in the workflow
const content = engine.createContent({
  contentType: 'text',
  workflowId: 'write-and-publish',
  data: { title: 'My Article', content: 'Article content...' },
  metadata: { title: 'My Article' },
  createdBy: 'user1',
  updatedBy: 'user1'
});

// Transition content to next stage
const result = engine.transitionContent(content.id, 'publish', 'user1');
if (result.success) {
  console.log('Content moved to publish stage');
}

API Reference

EditorialWorkflowEngine

The main engine for managing workflows and content.

registerWorkflow(workflow)

Register a new workflow.

const workflow = WorkflowTemplates.writeAndPublish();
engine.registerWorkflow(workflow);

createContent(content)

Create new content in a workflow.

const content = engine.createContent({
  contentType: 'text',
  workflowId: 'write-and-publish',
  data: { title: 'My Article', content: 'Article content...' },
  metadata: { title: 'My Article' },
  createdBy: 'user1',
  updatedBy: 'user1'
});

transitionContent(contentId, toStage, userId, data?)

Move content to a different stage.

const result = engine.transitionContent(contentId, 'publish', 'user1');
if (result.success) {
  console.log('Content moved to:', result.newStage);
}

getStateMachine(contentId)

Get the current state and available transitions for content.

const stateMachine = engine.getStateMachine(contentId);
console.log('Current stage:', stateMachine.currentState);
console.log('Available transitions:', stateMachine.availableTransitions);

WorkflowBuilder

Build custom workflows programmatically.

const workflow = new WorkflowBuilder()
  .id('my-workflow')
  .name('My Custom Workflow')
  .description('A custom workflow for my content')
  .addStage({
    id: 'draft',
    name: 'Draft',
    isPublishStage: false,
    allowsScheduling: false,
    description: 'Initial draft creation'
  })
  .addStage({
    id: 'review',
    name: 'Review',
    isPublishStage: false,
    allowsScheduling: false,
    description: 'Content review',
    permissions: ['content.review']
  })
  .addStage({
    id: 'publish',
    name: 'Publish',
    isPublishStage: true,
    allowsScheduling: true,
    description: 'Publish content'
  })
  .linear()
  .build();

WorkflowTemplates

Pre-built workflow templates for common use cases.

writeAndPublish()

Simple workflow with write and publish stages.

const workflow = WorkflowTemplates.writeAndPublish();

editorialWithReview()

Workflow with write, review, and publish stages.

const workflow = WorkflowTemplates.editorialWithReview();

complexEditorial()

Complex workflow with multiple review and approval stages.

const workflow = WorkflowTemplates.complexEditorial();

blogPost()

Workflow specifically designed for blog post creation.

const workflow = WorkflowTemplates.blogPost();

Workflow Configuration

EditorialStage

Define workflow stages with specific properties.

interface EditorialStage {
  id: string;                    // Unique stage identifier
  name: string;                  // Human-readable name
  order: number;                 // Order in workflow (1-based)
  isPublishStage: boolean;       // Whether this stage publishes content
  allowsScheduling: boolean;     // Whether this stage allows scheduling
  nextStage?: string;            // Next stage ID (optional)
  permissions?: string[];        // Required permissions
  active?: boolean;              // Whether stage is active
  description?: string;          // Stage description
  color?: string;                // UI color
  icon?: string;                 // UI icon
}

WorkflowTransition

Define how content moves between stages.

interface WorkflowTransition {
  from: string;                  // Source stage ID
  to: string;                    // Target stage ID
  permissions?: string[];        // Required permissions
  automatic?: boolean;           // Whether transition is automatic
  conditions?: TransitionCondition[]; // Conditions for automatic transition
  requiresApproval?: boolean;    // Whether transition requires approval
  notifications?: NotificationConfig[]; // Notification settings
}

Event System

Listen to workflow events for integration with other systems.

// Add event handler
const handlerId = engine.onEvent((event) => {
  console.log('Workflow event:', event.type, event.contentId);
});

// Remove event handler
engine.offEvent(handlerId);

Event Types

• content_created: Content created in workflow
• stage_changed: Content moved to different stage
• content_updated: Content updated
• workflow_completed: Workflow completed
• workflow_failed: Workflow failed

Validation

The engine includes built-in workflow validation.

const validation = engine.validateWorkflow(workflow);
if (!validation.valid) {
  console.error('Workflow validation errors:', validation.errors);
}

Examples

Basic Content Workflow

import { EditorialWorkflowEngine, WorkflowTemplates } from '@bernierllc/content-editorial-workflow';

const engine = new EditorialWorkflowEngine();

// Register a simple workflow
const workflow = WorkflowTemplates.writeAndPublish();
engine.registerWorkflow(workflow);

// Create content
const content = engine.createContent({
  contentType: 'article',
  workflowId: 'write-and-publish',
  data: {
    title: 'Getting Started with Workflows',
    content: 'This is a comprehensive guide...'
  },
  metadata: {
    title: 'Getting Started with Workflows',
    tags: ['tutorial', 'workflow'],
    priority: 'medium'
  },
  createdBy: 'author1',
  updatedBy: 'author1'
});

// Publish content
const result = engine.transitionContent(content.id, 'publish', 'author1');
if (result.success) {
  console.log('Article published successfully!');
}

Custom Workflow with Permissions

import { WorkflowBuilder } from '@bernierllc/content-editorial-workflow';

const workflow = new WorkflowBuilder()
  .id('editorial-workflow')
  .name('Editorial Workflow')
  .description('Workflow with review and approval stages')
  .addStage({
    id: 'draft',
    name: 'Draft',
    isPublishStage: false,
    allowsScheduling: false,
    description: 'Initial draft creation'
  })
  .addStage({
    id: 'edit',
    name: 'Edit',
    isPublishStage: false,
    allowsScheduling: false,
    description: 'Content editing and refinement',
    permissions: ['content.edit']
  })
  .addStage({
    id: 'review',
    name: 'Review',
    isPublishStage: false,
    allowsScheduling: false,
    description: 'Content review for quality',
    permissions: ['content.review']
  })
  .addStage({
    id: 'approval',
    name: 'Approval',
    isPublishStage: false,
    allowsScheduling: false,
    description: 'Final approval before publishing',
    permissions: ['content.approve']
  })
  .addStage({
    id: 'publish',
    name: 'Publish',
    isPublishStage: true,
    allowsScheduling: true,
    description: 'Publish content'
  })
  .linear()
  .build();

Event Handling

// Set up event handling
engine.onEvent((event) => {
  switch (event.type) {
    case 'content_created':
      console.log(`New content created: ${event.contentId}`);
      break;
    case 'stage_changed':
      console.log(`Content ${event.contentId} moved to stage ${event.stageId}`);
      break;
    case 'workflow_completed':
      console.log(`Workflow completed for content ${event.contentId}`);
      break;
  }
});

TypeScript Support

This package is written in TypeScript and provides full type definitions. All interfaces and types are exported for use in your own code.

Integration Status

Logger Integration

Status: not-applicable - Core workflow engine with minimal logging needs. This is a pure state machine implementation that does not require structured logging.

Docs-Suite Integration

Status: ready - Complete API documentation via TypeDoc with markdown examples and comprehensive usage guides.

NeverHub Integration

Status: not-applicable - Core state machine package without service discovery requirements. This package provides foundational workflow logic and does not need runtime service coordination.

License

UNLICENSED - See LICENSE file for details.

Contributing

Contributions are welcome! Please see the contributing guidelines for more information.

Support

For support and questions, please open an issue on GitHub.