business-as-code 2.1.3 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # business-as-code
 
+## 2.3.0
+
+### Patch Changes
+
+- Updated dependencies [9e2779a]
+- Updated dependencies [b7c7c57]
+  - ai-functions@2.3.0
+  - ai-database@2.3.0
+  - digital-workers@2.3.0
+
 ## 2.1.3
 
 ### Patch Changes

package/README.md

@@ -1,5 +1,7 @@
 # business-as-code
 
+![Stability: Experimental](https://img.shields.io/badge/stability-experimental-red)
+
 Primitives for expressing business logic, strategy, and operations as code. Define your entire business model—from vision and goals to products, services, processes, KPIs, OKRs, and financials—in a declarative, type-safe way.
 
 ## Installation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "business-as-code",
-  "version": "2.1.3",
+  "version": "2.3.0",
   "description": "Primitives for expressing business logic and processes as code",
   "type": "module",
   "main": "dist/index.js",
@@ -11,23 +11,26 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "clean": "rm -rf dist"
+  },
   "dependencies": {
-    "ai-database": "2.1.3",
-    "ai-functions": "2.1.3"
+    "ai-database": "2.3.0",
+    "ai-functions": "2.3.0",
+    "digital-workers": "2.3.0",
+    "org.ai": "0.0.1"
   },
+  "devDependencies": {},
   "keywords": [
     "business",
     "logic",
     "code",
     "primitives"
   ],
-  "license": "MIT",
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "vitest",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "clean": "rm -rf dist"
-  }
-}
+  "license": "MIT"
+}

package/src/dollar.ts

@@ -57,7 +57,10 @@ export function createBusinessOperations(initialContext?: BusinessContext): Busi
 
   return {
     format: (amount: number, currency?: Currency) => {
-      return formatCurrency(amount, currency || context.business?.metadata?.currency as Currency || 'USD')
+      return formatCurrency(
+        amount,
+        currency || (context.business?.metadata?.['currency'] as Currency) || 'USD'
+      )
     },
 
     percent: (value: number, total: number) => {
@@ -126,7 +129,7 @@ export function getContext(): BusinessContext {
  * Reset business context
  */
 export function resetContext(): void {
-  Object.keys($.context).forEach(key => {
+  Object.keys($.context).forEach((key) => {
     delete $.context[key]
   })
 }

package/src/entities/organization.ts

@@ -3,10 +3,16 @@
  *
  * Organizational hierarchy: Organization, Department, Team, Position, Role.
  *
+ * Uses digital-workers Worker type for position holders.
+ *
  * @packageDocumentation
  */
 
 import type { Noun } from 'ai-database'
+import type { Worker as DigitalWorker, WorkerRef } from 'digital-workers'
+
+// Re-export for convenience
+export type { DigitalWorker, WorkerRef }
 
 // =============================================================================
 // Organization
@@ -109,23 +115,9 @@ export const Organization: Noun = {
     },
   },
 
-  actions: [
-    'create',
-    'update',
-    'restructure',
-    'merge',
-    'split',
-    'archive',
-  ],
+  actions: ['create', 'update', 'restructure', 'merge', 'split', 'archive'],
 
-  events: [
-    'created',
-    'updated',
-    'restructured',
-    'merged',
-    'split',
-    'archived',
-  ],
+  events: ['created', 'updated', 'restructured', 'merged', 'split', 'archived'],
 }
 
 // =============================================================================
@@ -164,7 +156,18 @@ export const Department: Noun = {
       type: 'string',
       optional: true,
       description: 'Department type',
-      examples: ['engineering', 'product', 'design', 'marketing', 'sales', 'operations', 'finance', 'hr', 'legal', 'support'],
+      examples: [
+        'engineering',
+        'product',
+        'design',
+        'marketing',
+        'sales',
+        'operations',
+        'finance',
+        'hr',
+        'legal',
+        'support',
+      ],
     },
 
     // Budget
@@ -440,7 +443,17 @@ export const Position: Noun = {
       type: 'string',
       optional: true,
       description: 'Job level',
-      examples: ['intern', 'junior', 'mid', 'senior', 'staff', 'principal', 'director', 'vp', 'c-level'],
+      examples: [
+        'intern',
+        'junior',
+        'mid',
+        'senior',
+        'staff',
+        'principal',
+        'director',
+        'vp',
+        'c-level',
+      ],
     },
     track: {
       type: 'string',

package/src/goals.ts

@@ -1,8 +1,73 @@
 /**
  * Business goals definition and tracking
+ *
+ * Uses org.ai Goal types for standardized goal definitions across the ecosystem.
  */
 
 import type { GoalDefinition } from './types.js'
+import type {
+  Goal as OrgGoal,
+  Goals as OrgGoals,
+  GoalStatus,
+  GoalCategory,
+  GoalPriority,
+} from 'org.ai'
+
+// Re-export org.ai goal types for convenience
+export type { OrgGoal, OrgGoals, GoalStatus, GoalCategory, GoalPriority }
+
+/**
+ * Convert a business-as-code GoalDefinition to an org.ai Goal
+ *
+ * @param definition - Business goal definition
+ * @param id - Unique identifier for the goal
+ * @returns org.ai Goal object
+ */
+export function toOrgGoal(definition: GoalDefinition, id: string): OrgGoal {
+  const result: OrgGoal = {
+    id,
+    name: definition.name,
+    description: definition.description || definition.name,
+    target: 100,
+    progress: definition.progress || 0,
+    status: definition.status || 'not-started',
+  }
+  if (definition.targetDate) {
+    result.targetDate = definition.targetDate
+    result.deadline = definition.targetDate
+  }
+  if (definition.owner) result.owner = definition.owner
+  if (definition.category) result.category = definition.category
+  if (definition.metrics) result.metrics = definition.metrics
+  if (definition.dependencies) result.dependencies = definition.dependencies
+  if (definition.metadata) result.metadata = definition.metadata
+  return result
+}
+
+/**
+ * Convert an org.ai Goal to a business-as-code GoalDefinition
+ *
+ * @param goal - org.ai Goal object
+ * @returns Business goal definition
+ */
+export function fromOrgGoal(goal: OrgGoal): GoalDefinition {
+  const result: GoalDefinition = {
+    name: goal.name,
+    progress: typeof goal.progress === 'number' ? goal.progress : 0,
+  }
+  if (goal.description) result.description = goal.description
+  const cat = goal.category
+  if (cat) result.category = cat as NonNullable<GoalDefinition['category']>
+  if (goal.targetDate) result.targetDate = goal.targetDate
+  else if (goal.deadline) result.targetDate = goal.deadline
+  if (goal.owner) result.owner = goal.owner
+  if (goal.metrics) result.metrics = goal.metrics
+  const st = goal.status
+  if (st) result.status = st as NonNullable<GoalDefinition['status']>
+  if (goal.dependencies) result.dependencies = goal.dependencies
+  if (goal.metadata) result.metadata = goal.metadata
+  return result
+}
 
 /**
  * Define a business goal with metrics and tracking
@@ -35,7 +100,7 @@ import type { GoalDefinition } from './types.js'
  * ```
  */
 export function Goals(definitions: GoalDefinition[]): GoalDefinition[] {
-  return definitions.map(goal => validateAndNormalizeGoal(goal))
+  return definitions.map((goal) => validateAndNormalizeGoal(goal))
 }
 
 /**
@@ -73,20 +138,21 @@ export function updateProgress(goal: GoalDefinition, progress: number): GoalDefi
   }
 
   // Auto-update status based on progress
-  let status = goal.status
+  let status: GoalDefinition['status']
   if (progress === 0) {
     status = 'not-started'
   } else if (progress === 100) {
     status = 'completed'
-  } else if (progress > 0) {
+  } else {
     status = 'in-progress'
   }
 
-  return {
+  const result: GoalDefinition = {
     ...goal,
     progress,
-    status,
   }
+  if (status !== undefined) result.status = status
+  return result
 }
 
 /**
@@ -125,7 +191,7 @@ export function getGoalsByCategory(
   goals: GoalDefinition[],
   category: GoalDefinition['category']
 ): GoalDefinition[] {
-  return goals.filter(g => g.category === category)
+  return goals.filter((g) => g.category === category)
 }
 
 /**
@@ -135,14 +201,14 @@ export function getGoalsByStatus(
   goals: GoalDefinition[],
   status: GoalDefinition['status']
 ): GoalDefinition[] {
-  return goals.filter(g => g.status === status)
+  return goals.filter((g) => g.status === status)
 }
 
 /**
  * Get goals by owner
  */
 export function getGoalsByOwner(goals: GoalDefinition[], owner: string): GoalDefinition[] {
-  return goals.filter(g => g.owner === owner)
+  return goals.filter((g) => g.owner === owner)
 }
 
 /**
@@ -159,7 +225,7 @@ export function calculateOverallProgress(goals: GoalDefinition[]): number {
  * Check for circular dependencies
  */
 export function hasCircularDependencies(goals: GoalDefinition[]): boolean {
-  const goalMap = new Map(goals.map(g => [g.name, g]))
+  const goalMap = new Map(goals.map((g) => [g.name, g]))
 
   function checkCircular(goalName: string, visited = new Set<string>()): boolean {
     if (visited.has(goalName)) return true
@@ -178,14 +244,14 @@ export function hasCircularDependencies(goals: GoalDefinition[]): boolean {
     return false
   }
 
-  return goals.some(goal => checkCircular(goal.name))
+  return goals.some((goal) => checkCircular(goal.name))
 }
 
 /**
  * Get goals in dependency order
  */
 export function sortByDependencies(goals: GoalDefinition[]): GoalDefinition[] {
-  const goalMap = new Map(goals.map(g => [g.name, g]))
+  const goalMap = new Map(goals.map((g) => [g.name, g]))
   const sorted: GoalDefinition[] = []
   const visited = new Set<string>()
 
@@ -230,7 +296,7 @@ export function validateGoals(goals: GoalDefinition[]): { valid: boolean; errors
     }
 
     if (goal.dependencies) {
-      const goalNames = new Set(goals.map(g => g.name))
+      const goalNames = new Set(goals.map((g) => g.name))
       for (const dep of goal.dependencies) {
         if (!goalNames.has(dep)) {
           errors.push(`Goal ${goal.name} depends on unknown goal: ${dep}`)

package/src/index.ts

@@ -114,12 +114,7 @@ export {
 } from './business.js'
 
 // Export vision functions
-export {
-  Vision,
-  checkIndicator,
-  calculateProgress,
-  validateVision,
-} from './vision.js'
+export { Vision, checkIndicator, calculateProgress, validateVision } from './vision.js'
 
 // Export goal functions
 export {
@@ -136,6 +131,22 @@ export {
   hasCircularDependencies,
   sortByDependencies,
   validateGoals,
+  // org.ai conversions
+  toOrgGoal,
+  fromOrgGoal,
+} from './goals.js'
+
+// Re-export org.ai goal types
+export type {
+  OrgGoal,
+  OrgGoals,
+  GoalStatus,
+  GoalCategory,
+  GoalPriority,
+  // Aliased versions for backward compatibility
+  GoalStatus as OrgGoalStatus,
+  GoalCategory as OrgGoalCategory,
+  GoalPriority as OrgGoalPriority,
 } from './goals.js'
 
 // Export product functions
@@ -218,8 +229,14 @@ export {
   formatValue,
   comparePerformance,
   validateKPIs,
+  // org.ai conversions
+  toOrgKPI,
+  fromOrgKPI,
 } from './kpis.js'
 
+// Re-export org.ai KPI types
+export type { OrgKPI, KPICategory, KPITrend, KPIFrequency, KPIHistoryEntry } from './kpis.js'
+
 // Export OKR functions
 export {
   okrs,
@@ -239,8 +256,16 @@ export {
   formatKeyResult,
   compareOKRPerformance,
   validateOKRs,
+  // org.ai conversions
+  toOrgOKR,
+  fromOrgOKR,
+  toOrgKeyResult,
+  fromOrgKeyResult,
 } from './okrs.js'
 
+// Re-export org.ai OKR types
+export type { OrgOKR, OrgKeyResult, OKRStatus, KeyResultStatus } from './okrs.js'
+
 // Export financial functions
 export {
   financials,
@@ -272,13 +297,7 @@ export {
 } from './financials.js'
 
 // Export $ helper and context management
-export {
-  $,
-  createBusinessOperations,
-  updateContext,
-  getContext,
-  resetContext,
-} from './dollar.js'
+export { $, createBusinessOperations, updateContext, getContext, resetContext } from './dollar.js'
 
 // Export SaaS metrics
 export type {
@@ -419,8 +438,15 @@ export type {
   AssigneeRef,
   TaskRoutingRule,
   WorkflowRole,
+  // Re-exported from org.ai and digital-workers
+  OrgRole,
+  OrgRoleType,
+  RoleWorkerType,
 } from './roles.js'
 
+// Re-export Worker types from digital-workers via roles.ts
+export type { Worker, WorkerRef } from './roles.js'
+
 export {
   StandardBusinessRoles,
   createBusinessRole,
@@ -431,6 +457,9 @@ export {
   findRoleForTask,
   createTaskAssignment,
   transitionTaskStatus,
+  // Conversion helpers
+  workerRefToAssignee,
+  assigneeToWorkerRef,
 } from './roles.js'
 
 // Export organization (full hierarchy to FGA/RBAC)
@@ -455,11 +484,7 @@ export type {
   ResolvedPermissions,
 } from './organization.js'
 
-export {
-  resolvePermissions,
-  getApprovalChainForRequest,
-  findManager,
-} from './organization.js'
+export { resolvePermissions, getApprovalChainForRequest, findManager } from './organization.js'
 
 // =============================================================================
 // Entity Definitions (Noun pattern with Properties, Actions, Events)
@@ -528,3 +553,8 @@ export {
   Entities,
   type BusinessEntityCategory,
 } from './entities/index.js'
+
+// =============================================================================
+// Business Model Canvas (TODO: implement canvas module)
+// =============================================================================
+// Canvas functionality is planned but not yet implemented

package/src/kpis.ts

@@ -1,8 +1,63 @@
 /**
  * Key Performance Indicators (KPIs) management
+ *
+ * Uses org.ai KPI types for standardized KPI definitions across the ecosystem.
  */
 
 import type { KPIDefinition, TimePeriod } from './types.js'
+import type { KPI as OrgKPI, KPICategory, KPITrend, KPIFrequency, KPIHistoryEntry } from 'org.ai'
+
+// Re-export org.ai KPI types for convenience
+export type { OrgKPI, KPICategory, KPITrend, KPIFrequency, KPIHistoryEntry }
+
+/**
+ * Convert a business-as-code KPIDefinition to an org.ai KPI
+ *
+ * @param definition - Business KPI definition
+ * @param id - Unique identifier for the KPI
+ * @returns org.ai KPI object
+ */
+export function toOrgKPI(definition: KPIDefinition, id: string): OrgKPI {
+  const result: OrgKPI = {
+    id,
+    name: definition.name,
+    value: definition.current ?? 0,
+    target: definition.target ?? 0,
+    unit: definition.unit || '',
+  }
+  if (definition.description !== undefined) result.description = definition.description
+  if (definition.current !== undefined) result.current = definition.current
+  if (definition.category !== undefined) result.category = definition.category as KPICategory
+  if (definition.frequency !== undefined) result.frequency = definition.frequency as KPIFrequency
+  if (definition.dataSource !== undefined) result.dataSource = definition.dataSource
+  if (definition.formula !== undefined) result.formula = definition.formula
+  if (definition.metadata !== undefined) result.metadata = definition.metadata
+  return result
+}
+
+/**
+ * Convert an org.ai KPI to a business-as-code KPIDefinition
+ *
+ * @param kpi - org.ai KPI object
+ * @returns Business KPI definition
+ */
+export function fromOrgKPI(kpi: OrgKPI): KPIDefinition {
+  const result: KPIDefinition = {
+    name: kpi.name,
+    unit: kpi.unit,
+  }
+  if (kpi.description !== undefined) result.description = kpi.description
+  const cat = kpi.category
+  if (cat !== undefined) result.category = cat as NonNullable<KPIDefinition['category']>
+  if (typeof kpi.target === 'number') result.target = kpi.target
+  if (typeof kpi.value === 'number') result.current = kpi.value
+  else if (typeof kpi.current === 'number') result.current = kpi.current
+  if (kpi.frequency !== undefined) result.frequency = kpi.frequency as TimePeriod
+  if (kpi.dataSource !== undefined) result.dataSource = kpi.dataSource
+  if (kpi.formula !== undefined) result.formula = kpi.formula
+  if (kpi.metadata !== undefined) result.metadata = kpi.metadata
+  return result
+}
 
 /**
  * Define Key Performance Indicators for tracking business metrics
@@ -46,7 +101,7 @@ import type { KPIDefinition, TimePeriod } from './types.js'
  * ```
  */
 export function kpis(definitions: KPIDefinition[]): KPIDefinition[] {
-  return definitions.map(kpi => validateAndNormalizeKPI(kpi))
+  return definitions.map((kpi) => validateAndNormalizeKPI(kpi))
 }
 
 /**
@@ -88,7 +143,7 @@ export function meetsTarget(kpi: KPIDefinition): boolean {
   if (kpi.target === undefined || kpi.current === undefined) return false
 
   // For metrics where lower is better (like churn rate)
-  const lowerIsBetter = ['churn', 'cost', 'time', 'error', 'downtime'].some(term =>
+  const lowerIsBetter = ['churn', 'cost', 'time', 'error', 'downtime'].some((term) =>
     kpi.name.toLowerCase().includes(term)
   )
 
@@ -126,14 +181,14 @@ export function getKPIsByCategory(
   kpis: KPIDefinition[],
   category: KPIDefinition['category']
 ): KPIDefinition[] {
-  return kpis.filter(k => k.category === category)
+  return kpis.filter((k) => k.category === category)
 }
 
 /**
  * Get KPIs by frequency
  */
 export function getKPIsByFrequency(kpis: KPIDefinition[], frequency: TimePeriod): KPIDefinition[] {
-  return kpis.filter(k => k.frequency === frequency)
+  return kpis.filter((k) => k.frequency === frequency)
 }
 
 /**
@@ -147,7 +202,7 @@ export function getKPIsOnTarget(kpis: KPIDefinition[]): KPIDefinition[] {
  * Get KPIs that don't meet their targets
  */
 export function getKPIsOffTarget(kpis: KPIDefinition[]): KPIDefinition[] {
-  return kpis.filter(kpi => !meetsTarget(kpi))
+  return kpis.filter((kpi) => !meetsTarget(kpi))
 }
 
 /**
@@ -235,11 +290,10 @@ export function comparePerformance(
   }
 
   const change = current.current - previous.current
-  const changePercent =
-    previous.current !== 0 ? (change / previous.current) * 100 : 0
+  const changePercent = previous.current !== 0 ? (change / previous.current) * 100 : 0
 
   // Determine if change is an improvement
-  const lowerIsBetter = ['churn', 'cost', 'time', 'error', 'downtime'].some(term =>
+  const lowerIsBetter = ['churn', 'cost', 'time', 'error', 'downtime'].some((term) =>
     current.name.toLowerCase().includes(term)
   )