business-as-code 2.1.3 → 2.3.0

package/src/roles.ts

@@ -9,6 +9,13 @@
  * @packageDocumentation
  */
 
+import type { Role as OrgRole, RoleType as OrgRoleType, RoleWorkerType } from 'org.ai'
+import type { Worker, WorkerRef } from 'digital-workers'
+
+// Re-export for convenience
+export type { Worker, WorkerRef } from 'digital-workers'
+export type { OrgRole, OrgRoleType, RoleWorkerType }
+
 // =============================================================================
 // Business Role - Bridges Worker Role and Authorization
 // =============================================================================
@@ -43,7 +50,10 @@ export type BusinessRoleType =
   | string
 
 /**
- * Business Role - extends WorkerRole with authorization and task capabilities
+ * Business Role - extends org.ai Role with authorization and task capabilities
+ *
+ * Composes with org.ai Role to provide additional business-specific properties
+ * like authorization permissions, task capabilities, and compensation.
  *
  * @example
  * ```ts
@@ -54,6 +64,9 @@ export type BusinessRoleType =
  *   department: 'Engineering',
  *   description: 'Leads engineering team and makes technical decisions',
  *
+ *   // From org.ai Role
+ *   skills: ['TypeScript', 'Architecture', 'Team Leadership'],
+ *
  *   // Business responsibilities
  *   responsibilities: [
  *     'Lead engineering team',
@@ -78,28 +91,10 @@ export type BusinessRoleType =
  * }
  * ```
  */
-export interface BusinessRole {
-  /** Unique role identifier */
-  id: string
-
-  /** Role display name */
-  name: string
-
-  /** Role type classification */
+export interface BusinessRole extends Omit<OrgRole, 'permissions'> {
+  /** Role type classification (overrides OrgRole.type with business-specific types) */
   type: BusinessRoleType
 
-  /** Department or team */
-  department?: string
-
-  /** Human-readable description */
-  description?: string
-
-  /** Key responsibilities */
-  responsibilities?: string[]
-
-  /** Required skills */
-  skills?: string[]
-
   /**
    * Authorization permissions by resource type
    *
@@ -107,6 +102,8 @@ export interface BusinessRole {
    * - 'read', 'edit', 'delete', 'manage' (standard)
    * - 'act:*' or 'act:verb' (domain-specific verbs)
    *
+   * Note: This differs from OrgRole.permissions which is string[]
+   *
    * @example
    * ```ts
    * permissions: {
@@ -118,32 +115,8 @@ export interface BusinessRole {
    */
   permissions?: Record<string, string[]>
 
-  /** Task types this role can handle */
-  canHandle?: string[]
-
-  /** Task types this role can delegate to others */
-  canDelegate?: string[]
-
-  /** Request types this role can approve */
-  canApprove?: string[]
-
-  /** Escalation path - role to escalate to */
-  escalateTo?: string
-
-  /** Reports to - manager role */
-  reportsTo?: string
-
-  /** Worker type preference: 'ai' | 'human' | 'hybrid' */
-  workerType?: 'ai' | 'human' | 'hybrid'
-
-  /** Level in hierarchy (1 = entry, higher = more senior) */
-  level?: number
-
   /** Compensation band */
   compensationBand?: string
-
-  /** Additional metadata */
-  metadata?: Record<string, unknown>
 }
 
 // =============================================================================
@@ -263,6 +236,8 @@ export interface TaskAssignment {
 
 /**
  * Reference to an assignee (worker, team, or role)
+ *
+ * Compatible with digital-workers WorkerRef for worker assignments.
  */
 export interface AssigneeRef {
   /** Type of assignee */
@@ -273,6 +248,34 @@ export interface AssigneeRef {
   name?: string
 }
 
+/**
+ * Convert a digital-workers WorkerRef to an AssigneeRef
+ */
+export function workerRefToAssignee(workerRef: WorkerRef): AssigneeRef {
+  const result: AssigneeRef = {
+    type: 'worker',
+    id: workerRef.id,
+  }
+  if (workerRef.name !== undefined) {
+    result.name = workerRef.name
+  }
+  return result
+}
+
+/**
+ * Convert an AssigneeRef to a digital-workers WorkerRef (if type is 'worker')
+ */
+export function assigneeToWorkerRef(assignee: AssigneeRef): WorkerRef | null {
+  if (assignee.type !== 'worker') return null
+  const result: WorkerRef = {
+    id: assignee.id,
+  }
+  if (assignee.name !== undefined) {
+    result.name = assignee.name
+  }
+  return result
+}
+
 // =============================================================================
 // Role-Based Task Routing
 // =============================================================================
@@ -549,8 +552,8 @@ export function createBusinessRole(
 
   return {
     id,
-    name: standard.name || template,
-    type: standard.type || template,
+    name: standard['name'] || template,
+    type: standard['type'] || template,
     ...standard,
     ...overrides,
   } as BusinessRole
@@ -559,11 +562,7 @@ export function createBusinessRole(
 /**
  * Check if a role has permission for an action on a resource type
  */
-export function hasPermission(
-  role: BusinessRole,
-  resourceType: string,
-  action: string
-): boolean {
+export function hasPermission(role: BusinessRole, resourceType: string, action: string): boolean {
   if (!role.permissions) return false
 
   // Check wildcard permissions
@@ -595,24 +594,24 @@ export function hasPermission(
  * Check if a role can handle a task type
  */
 export function canHandleTask(role: BusinessRole, taskType: string): boolean {
-  if (!role.canHandle) return false
-  return role.canHandle.includes(taskType) || role.canHandle.includes('*')
+  if (!role['canHandle']) return false
+  return role['canHandle'].includes(taskType) || role['canHandle'].includes('*')
 }
 
 /**
  * Check if a role can approve a request type
  */
 export function canApproveRequest(role: BusinessRole, requestType: string): boolean {
-  if (!role.canApprove) return false
-  return role.canApprove.includes(requestType) || role.canApprove.includes('*')
+  if (!role['canApprove']) return false
+  return role['canApprove'].includes(requestType) || role['canApprove'].includes('*')
 }
 
 /**
  * Check if a role can delegate a task type
  */
 export function canDelegateTask(role: BusinessRole, taskType: string): boolean {
-  if (!role.canDelegate) return false
-  return role.canDelegate.includes(taskType) || role.canDelegate.includes('*')
+  if (!role['canDelegate']) return false
+  return role['canDelegate'].includes(taskType) || role['canDelegate'].includes('*')
 }
 
 /**
@@ -623,7 +622,7 @@ export function findRoleForTask(
   rules: TaskRoutingRule[],
   context?: { amount?: number; skills?: string[] }
 ): TaskRoutingRule | undefined {
-  const matchingRules = rules.filter(rule => rule.taskType === taskType)
+  const matchingRules = rules.filter((rule) => rule.taskType === taskType)
 
   if (matchingRules.length === 0) return undefined
 
@@ -633,7 +632,7 @@ export function findRoleForTask(
       if (rule.escalateAbove && context.amount > rule.escalateAbove) {
         // Find the escalated rule
         const escalatedRule = rules.find(
-          r => r.taskType === taskType && r.requiredRole === rule.escalateTo
+          (r) => r.taskType === taskType && r.requiredRole === rule.escalateTo
         )
         if (escalatedRule) return escalatedRule
       }
@@ -651,7 +650,9 @@ export function createTaskAssignment(
   taskId: string,
   taskType: string,
   assignee: AssigneeRef,
-  options?: Partial<Omit<TaskAssignment, 'id' | 'taskId' | 'taskType' | 'assignee' | 'status' | 'assignedAt'>>
+  options?: Partial<
+    Omit<TaskAssignment, 'id' | 'taskId' | 'taskType' | 'assignee' | 'status' | 'assignedAt'>
+  >
 ): TaskAssignment {
   return {
     id: `assign_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,

package/src/workflow.ts

@@ -88,20 +88,23 @@ export function getActionsByType(
   workflow: WorkflowDefinition,
   type: WorkflowAction['type']
 ): WorkflowAction[] {
-  return workflow.actions?.filter(action => action.type === type) || []
+  return workflow.actions?.filter((action) => action.type === type) || []
 }
 
 /**
  * Get conditional actions
  */
 export function getConditionalActions(workflow: WorkflowDefinition): WorkflowAction[] {
-  return workflow.actions?.filter(action => action.condition) || []
+  return workflow.actions?.filter((action) => action.condition) || []
 }
 
 /**
  * Add action to workflow
  */
-export function addAction(workflow: WorkflowDefinition, action: WorkflowAction): WorkflowDefinition {
+export function addAction(
+  workflow: WorkflowDefinition,
+  action: WorkflowAction
+): WorkflowDefinition {
   return {
     ...workflow,
     actions: [...(workflow.actions || []), action],
@@ -112,10 +115,10 @@ export function addAction(workflow: WorkflowDefinition, action: WorkflowAction):
  * Remove action from workflow
  */
 export function removeAction(workflow: WorkflowDefinition, order: number): WorkflowDefinition {
-  return {
-    ...workflow,
-    actions: workflow.actions?.filter(a => a.order !== order),
-  }
+  const actions = workflow.actions?.filter((a) => a.order !== order)
+  const result: WorkflowDefinition = { ...workflow }
+  if (actions !== undefined) result.actions = actions
+  return result
 }
 
 /**
@@ -126,14 +129,13 @@ export function updateAction(
   order: number,
   updates: Partial<WorkflowAction>
 ): WorkflowDefinition {
-  const actions = workflow.actions?.map(action =>
+  const actions = workflow.actions?.map((action) =>
     action.order === order ? { ...action, ...updates } : action
   )
 
-  return {
-    ...workflow,
-    actions,
-  }
+  const result: WorkflowDefinition = { ...workflow }
+  if (actions !== undefined) result.actions = actions
+  return result
 }
 
 /**
@@ -161,7 +163,9 @@ export function isWebhookTrigger(trigger: WorkflowTrigger): boolean {
  * Parse wait duration to milliseconds
  */
 export function parseWaitDuration(duration: string): number {
-  const match = duration.match(/(\d+)\s*(ms|millisecond|milliseconds|s|second|seconds|m|minute|minutes|h|hour|hours|d|day|days)/)
+  const match = duration.match(
+    /(\d+)\s*(ms|millisecond|milliseconds|s|second|seconds|m|minute|minutes|h|hour|hours|d|day|days)/
+  )
   if (!match) return 0
 
   const value = parseInt(match[1] || '0', 10)
@@ -234,7 +238,10 @@ function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
 /**
  * Validate workflow definition
  */
-export function validateWorkflow(workflow: WorkflowDefinition): { valid: boolean; errors: string[] } {
+export function validateWorkflow(workflow: WorkflowDefinition): {
+  valid: boolean
+  errors: string[]
+} {
   const errors: string[] = []
 
   if (!workflow.name) {
@@ -267,7 +274,7 @@ export function validateWorkflow(workflow: WorkflowDefinition): { valid: boolean
       orders.add(action.order)
 
       // Validate action-specific requirements
-      if (action.type === 'wait' && !action.params?.duration) {
+      if (action.type === 'wait' && !action.params?.['duration']) {
         errors.push(`Wait action at order ${action.order} must specify duration`)
       }
     }

package/test/business.test.ts

@@ -0,0 +1,282 @@
+/**
+ * Tests for business.ts - Business entity definition and management
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  Business,
+  getTotalBudget,
+  getTotalTeamSize,
+  getDepartment,
+  getTeam,
+  validateBusiness,
+} from '../src/business.js'
+import type { BusinessDefinition } from '../src/types.js'
+
+describe('Business', () => {
+  describe('Business()', () => {
+    it('should create a business entity with required fields', () => {
+      const business = Business({
+        name: 'Acme Corp',
+      })
+
+      expect(business.name).toBe('Acme Corp')
+      expect(business.values).toEqual([])
+      expect(business.teamSize).toBe(0)
+      expect(business.metadata).toEqual({})
+      expect(business.foundedAt).toBeInstanceOf(Date)
+    })
+
+    it('should create a business entity with all fields', () => {
+      const foundedDate = new Date('2020-01-01')
+      const business = Business({
+        name: 'Test Corp',
+        description: 'A test company',
+        industry: 'Technology',
+        mission: 'To innovate',
+        values: ['Innovation', 'Integrity'],
+        targetMarket: 'Enterprise',
+        foundedAt: foundedDate,
+        teamSize: 50,
+        structure: {
+          departments: [
+            {
+              name: 'Engineering',
+              head: 'Jane Smith',
+              members: ['Alice', 'Bob'],
+              budget: 1000000,
+            },
+          ],
+        },
+        metadata: { customField: 'value' },
+      })
+
+      expect(business.name).toBe('Test Corp')
+      expect(business.description).toBe('A test company')
+      expect(business.industry).toBe('Technology')
+      expect(business.mission).toBe('To innovate')
+      expect(business.values).toEqual(['Innovation', 'Integrity'])
+      expect(business.targetMarket).toBe('Enterprise')
+      expect(business.foundedAt).toBe(foundedDate)
+      expect(business.teamSize).toBe(50)
+      expect(business.structure?.departments).toHaveLength(1)
+      expect(business.metadata).toEqual({ customField: 'value' })
+    })
+
+    it('should throw error if name is empty', () => {
+      expect(() => Business({ name: '' })).toThrow('Business name is required')
+    })
+
+    it('should preserve provided values and not override with defaults', () => {
+      const business = Business({
+        name: 'Test',
+        values: ['Custom'],
+        teamSize: 100,
+      })
+
+      expect(business.values).toEqual(['Custom'])
+      expect(business.teamSize).toBe(100)
+    })
+  })
+
+  describe('getTotalBudget()', () => {
+    it('should return 0 if no departments', () => {
+      const business = Business({ name: 'Test' })
+      expect(getTotalBudget(business)).toBe(0)
+    })
+
+    it('should return 0 if structure has no departments', () => {
+      const business = Business({
+        name: 'Test',
+        structure: {},
+      })
+      expect(getTotalBudget(business)).toBe(0)
+    })
+
+    it('should calculate total budget across departments', () => {
+      const business = Business({
+        name: 'Test',
+        structure: {
+          departments: [
+            { name: 'Engineering', budget: 1000000 },
+            { name: 'Sales', budget: 500000 },
+            { name: 'HR' }, // No budget specified
+          ],
+        },
+      })
+
+      expect(getTotalBudget(business)).toBe(1500000)
+    })
+
+    it('should handle departments with zero budget', () => {
+      const business = Business({
+        name: 'Test',
+        structure: {
+          departments: [
+            { name: 'Engineering', budget: 1000000 },
+            { name: 'Sales', budget: 0 },
+          ],
+        },
+      })
+
+      expect(getTotalBudget(business)).toBe(1000000)
+    })
+  })
+
+  describe('getTotalTeamSize()', () => {
+    it('should return teamSize if no departments', () => {
+      const business = Business({ name: 'Test', teamSize: 50 })
+      expect(getTotalTeamSize(business)).toBe(50)
+    })
+
+    it('should return 0 if no teamSize and no departments', () => {
+      const business = Business({ name: 'Test' })
+      expect(getTotalTeamSize(business)).toBe(0)
+    })
+
+    it('should calculate total team size from department members', () => {
+      const business = Business({
+        name: 'Test',
+        structure: {
+          departments: [
+            { name: 'Engineering', members: ['Alice', 'Bob', 'Charlie'] },
+            { name: 'Sales', members: ['David', 'Eve'] },
+            { name: 'HR' }, // No members
+          ],
+        },
+      })
+
+      expect(getTotalTeamSize(business)).toBe(5)
+    })
+  })
+
+  describe('getDepartment()', () => {
+    const business = Business({
+      name: 'Test',
+      structure: {
+        departments: [
+          { name: 'Engineering', head: 'Jane' },
+          { name: 'Sales', head: 'John' },
+        ],
+      },
+    })
+
+    it('should find department by name', () => {
+      const dept = getDepartment(business, 'Engineering')
+      expect(dept?.name).toBe('Engineering')
+      expect(dept?.head).toBe('Jane')
+    })
+
+    it('should return undefined for non-existent department', () => {
+      const dept = getDepartment(business, 'Marketing')
+      expect(dept).toBeUndefined()
+    })
+
+    it('should return undefined if no structure', () => {
+      const simpleBusiness = Business({ name: 'Simple' })
+      const dept = getDepartment(simpleBusiness, 'Engineering')
+      expect(dept).toBeUndefined()
+    })
+  })
+
+  describe('getTeam()', () => {
+    const business = Business({
+      name: 'Test',
+      structure: {
+        teams: [
+          { name: 'Alpha', lead: 'Alice' },
+          { name: 'Beta', lead: 'Bob' },
+        ],
+      },
+    })
+
+    it('should find team by name', () => {
+      const team = getTeam(business, 'Alpha')
+      expect(team?.name).toBe('Alpha')
+      expect(team?.lead).toBe('Alice')
+    })
+
+    it('should return undefined for non-existent team', () => {
+      const team = getTeam(business, 'Gamma')
+      expect(team).toBeUndefined()
+    })
+
+    it('should return undefined if no structure', () => {
+      const simpleBusiness = Business({ name: 'Simple' })
+      const team = getTeam(simpleBusiness, 'Alpha')
+      expect(team).toBeUndefined()
+    })
+  })
+
+  describe('validateBusiness()', () => {
+    it('should validate valid business', () => {
+      const business = Business({
+        name: 'Valid Corp',
+        teamSize: 50,
+      })
+
+      const result = validateBusiness(business)
+      expect(result.valid).toBe(true)
+      expect(result.errors).toHaveLength(0)
+    })
+
+    it('should fail validation if name is missing', () => {
+      const business: BusinessDefinition = { name: '' }
+      const result = validateBusiness(business)
+
+      expect(result.valid).toBe(false)
+      expect(result.errors).toContain('Business name is required')
+    })
+
+    it('should fail validation if teamSize is negative', () => {
+      const business: BusinessDefinition = { name: 'Test', teamSize: -5 }
+      const result = validateBusiness(business)
+
+      expect(result.valid).toBe(false)
+      expect(result.errors).toContain('Team size cannot be negative')
+    })
+
+    it('should fail validation if department has no name', () => {
+      const business: BusinessDefinition = {
+        name: 'Test',
+        structure: {
+          departments: [{ name: '', budget: 1000 }],
+        },
+      }
+      const result = validateBusiness(business)
+
+      expect(result.valid).toBe(false)
+      expect(result.errors).toContain('Department name is required')
+    })
+
+    it('should fail validation if department budget is negative', () => {
+      const business: BusinessDefinition = {
+        name: 'Test',
+        structure: {
+          departments: [{ name: 'Engineering', budget: -1000 }],
+        },
+      }
+      const result = validateBusiness(business)
+
+      expect(result.valid).toBe(false)
+      expect(result.errors).toContain('Department Engineering budget cannot be negative')
+    })
+
+    it('should return multiple errors for multiple issues', () => {
+      const business: BusinessDefinition = {
+        name: '',
+        teamSize: -5,
+        structure: {
+          departments: [
+            { name: '', budget: 1000 },
+            { name: 'Sales', budget: -500 },
+          ],
+        },
+      }
+      const result = validateBusiness(business)
+
+      expect(result.valid).toBe(false)
+      expect(result.errors.length).toBeGreaterThan(1)
+    })
+  })
+})