business-as-code 2.1.1 → 2.1.3

package/dist/canvas/value.js

@@ -0,0 +1,21 @@
+/**
+ * Value Propositions
+ *
+ * Functions for creating and working with value propositions.
+ */
+/**
+ * Create a value proposition
+ */
+export function createValueProposition(input) {
+    const { name, description, valueType, benefits = [], targetSegments, quantifiedValue, segmentFit } = input;
+    return {
+        name,
+        description,
+        valueType,
+        benefits,
+        targetSegments,
+        quantifiedValue,
+        segmentFit,
+    };
+}
+//# sourceMappingURL=value.js.map

package/dist/canvas/value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value.js","sourceRoot":"","sources":["../../src/canvas/value.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAkC;IACvE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,GAAG,EAAE,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,KAAK,CAAA;IAE1G,OAAO;QACL,IAAI;QACJ,WAAW;QACX,SAAS;QACT,QAAQ;QACR,cAAc;QACd,eAAe;QACf,UAAU;KACX,CAAA;AACH,CAAC"}

package/dist/entities/planning.d.ts

@@ -1,87 +0,0 @@
-import type { Noun } from 'ai-database';
-/**
- * Planning Entities
- * Issue, Plan - Planning-focused abstractions for tracking work
- *
- * These complement the execution-focused Task in digital-tasks
- * and the project management entities in projects.ts
- *
- * Key distinction:
- * - Task (digital-tasks): Function execution with workers, queues, runtime
- * - Task (projects.ts): Project management work item
- * - Issue (planning.ts): Planning-focused with design, acceptance criteria, notes
- */
-/**
- * WorkItem - A planning-focused work item (ticket/issue)
- *
- * Models the full lifecycle of work from ideation through completion:
- * - What: title, description
- * - Why: context, business value
- * - How: design (implementation approach)
- * - Done: acceptance criteria
- * - Context: notes (session handoff, progress tracking)
- *
- * This abstraction is backend-agnostic and can be implemented by:
- * - beads (SQLite) - maps to beads Issue
- * - Linear - maps to Linear Issue
- * - GitHub Issues
- * - Jira - maps to Jira Issue/Ticket
- * - etc.
- *
- * Note: Distinct from entities/risk.ts Issue which represents
- * operational/business issues (problems requiring resolution).
- * WorkItem represents planned development work.
- */
-export declare const WorkItem: Noun;
-/**
- * Comment - A comment on an issue
- */
-export declare const Comment: Noun;
-/**
- * Event - An audit trail event on an issue
- */
-export declare const Event: Noun;
-/**
- * WorkItemComment - Alias for Comment (for clarity)
- */
-export declare const WorkItemComment: Noun;
-/**
- * WorkItemEvent - Alias for Event (for clarity)
- */
-export declare const WorkItemEvent: Noun;
-/**
- * Plan - A high-level planning document that generates issues
- *
- * Bridges Strategy → Plan → Issues → Tasks
- *
- * A Plan captures:
- * - Goals and objectives
- * - Constraints and assumptions
- * - Design decisions
- * - Issue breakdown
- */
-export declare const Plan: Noun;
-/**
- * Dependency types for issue relationships
- */
-export declare const DependencyTypes: {
-    /** Hard blocker - issue A blocks issue B from starting */
-    readonly blocks: "blocks";
-    /** Soft link - issues are related but not blocking */
-    readonly related: "related";
-    /** Hierarchical - epic/subtask relationship */
-    readonly parentChild: "parent-child";
-    /** Provenance - issue B discovered while working on A */
-    readonly discoveredFrom: "discovered-from";
-};
-export type DependencyType = (typeof DependencyTypes)[keyof typeof DependencyTypes];
-export declare const PlanningEntities: {
-    WorkItem: Noun;
-    WorkItemComment: Noun;
-    WorkItemEvent: Noun;
-    Comment: Noun;
-    Event: Noun;
-    Plan: Noun;
-};
-export default PlanningEntities;
-//# sourceMappingURL=planning.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "business-as-code",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Primitives for expressing business logic and processes as code",
   "type": "module",
   "main": "dist/index.js",
@@ -11,17 +11,9 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "vitest",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "clean": "rm -rf dist"
-  },
   "dependencies": {
-    "ai-database": "2.1.1",
-    "ai-functions": "2.1.1"
+    "ai-database": "2.1.3",
+    "ai-functions": "2.1.3"
   },
   "keywords": [
     "business",
@@ -29,5 +21,13 @@
     "code",
     "primitives"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "clean": "rm -rf dist"
+  }
+}

package/src/canvas/activities.ts

@@ -0,0 +1,32 @@
+/**
+ * Key Activities
+ *
+ * Functions for creating and working with key activities.
+ */
+
+import type { KeyActivity, ActivityCategory } from './types.js'
+
+export interface CreateKeyActivityInput {
+  name: string
+  category: ActivityCategory
+  description?: string
+  resources?: string[]
+  metrics?: string[]
+  uptime?: number
+}
+
+/**
+ * Create a key activity
+ */
+export function createKeyActivity(input: CreateKeyActivityInput): KeyActivity {
+  const { name, category, description, resources, metrics, uptime } = input
+
+  return {
+    name,
+    category,
+    description,
+    resources,
+    metrics,
+    uptime,
+  }
+}

package/src/canvas/canvas.ts

@@ -0,0 +1,482 @@
+/**
+ * Business Model Canvas
+ *
+ * Functions for creating, validating, and analyzing the Business Model Canvas.
+ */
+
+import type {
+  BusinessModelCanvas,
+  CanvasValidation,
+  CanvasSummary,
+  CanvasStrengthAnalysis,
+  CanvasGaps,
+  CustomerSegment,
+  ValueProposition,
+  Channel,
+  CustomerRelationship,
+  RevenueStream,
+  KeyResource,
+  KeyActivity,
+  KeyPartnership,
+  CostItem,
+} from './types.js'
+
+export interface CreateCanvasInput {
+  name: string
+  customerSegments: CustomerSegment[]
+  valuePropositions: ValueProposition[]
+  channels: Channel[]
+  customerRelationships: CustomerRelationship[]
+  revenueStreams: RevenueStream[]
+  keyResources: KeyResource[]
+  keyActivities: KeyActivity[]
+  keyPartnerships: KeyPartnership[]
+  costStructure: CostItem[]
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Create a Business Model Canvas
+ */
+export function createCanvas(input: CreateCanvasInput): BusinessModelCanvas {
+  return {
+    name: input.name,
+    customerSegments: input.customerSegments,
+    valuePropositions: input.valuePropositions,
+    channels: input.channels,
+    customerRelationships: input.customerRelationships,
+    revenueStreams: input.revenueStreams,
+    keyResources: input.keyResources,
+    keyActivities: input.keyActivities,
+    keyPartnerships: input.keyPartnerships,
+    costStructure: input.costStructure,
+    metadata: input.metadata,
+  }
+}
+
+/**
+ * Validate canvas completeness
+ */
+export function validateCanvas(canvas: BusinessModelCanvas): CanvasValidation {
+  const missingBlocks: string[] = []
+  const warnings: string[] = []
+
+  // Check each building block
+  if (canvas.customerSegments.length === 0) {
+    missingBlocks.push('customerSegments')
+  }
+
+  if (canvas.valuePropositions.length === 0) {
+    missingBlocks.push('valuePropositions')
+  }
+
+  if (canvas.channels.length === 0) {
+    missingBlocks.push('channels')
+  }
+
+  if (canvas.customerRelationships.length === 0) {
+    missingBlocks.push('customerRelationships')
+  }
+
+  if (canvas.revenueStreams.length === 0) {
+    missingBlocks.push('revenueStreams')
+  }
+
+  if (canvas.keyResources.length === 0) {
+    missingBlocks.push('keyResources')
+  }
+
+  if (canvas.keyActivities.length === 0) {
+    missingBlocks.push('keyActivities')
+  }
+
+  if (canvas.keyPartnerships.length === 0) {
+    missingBlocks.push('keyPartnerships')
+  }
+
+  if (canvas.costStructure.length === 0) {
+    missingBlocks.push('costStructure')
+  }
+
+  // Add warnings for incomplete data
+  if (canvas.customerSegments.some(s => !s.size)) {
+    warnings.push('Some customer segments are missing size estimates')
+  }
+
+  if (canvas.revenueStreams.some(r => !r.price && !r.pricePerUnit)) {
+    warnings.push('Some revenue streams are missing pricing information')
+  }
+
+  return {
+    isComplete: missingBlocks.length === 0,
+    missingBlocks,
+    warnings,
+  }
+}
+
+/**
+ * Generate canvas summary with key metrics
+ */
+export function generateCanvasSummary(canvas: BusinessModelCanvas): CanvasSummary {
+  // Calculate Total Addressable Market (TAM)
+  const totalAddressableMarket = canvas.customerSegments.reduce((sum, segment) => {
+    if (segment.size && segment.revenuePerCustomer) {
+      return sum + segment.size * segment.revenuePerCustomer
+    }
+    return sum
+  }, 0)
+
+  // Calculate projected annual revenue from revenue streams
+  const projectedAnnualRevenue = canvas.revenueStreams.reduce((sum, stream) => {
+    return sum + (stream.annualRevenue ?? 0)
+  }, 0)
+
+  // Calculate total annual costs
+  const totalAnnualCosts = canvas.costStructure.reduce((sum, cost) => {
+    if (cost.amount) {
+      // Normalize to annual
+      const multiplier = cost.period === 'monthly' ? 12 : cost.period === 'quarterly' ? 4 : 1
+      return sum + cost.amount * multiplier
+    }
+    if (cost.estimatedTotal) {
+      return sum + cost.estimatedTotal
+    }
+    return sum
+  }, 0)
+
+  // Calculate projected profit
+  const projectedProfit = projectedAnnualRevenue - totalAnnualCosts
+
+  return {
+    totalAddressableMarket,
+    projectedAnnualRevenue,
+    totalAnnualCosts,
+    projectedProfit,
+  }
+}
+
+/**
+ * Analyze canvas strength
+ */
+export function analyzeCanvasStrength(canvas: BusinessModelCanvas): CanvasStrengthAnalysis {
+  const blockScores: Record<string, number> = {}
+  const strengths: string[] = []
+  const weaknesses: string[] = []
+
+  // Score customer segments (0-100)
+  const segmentScore = scoreCustomerSegments(canvas.customerSegments)
+  blockScores['customerSegments'] = segmentScore
+  if (segmentScore >= 70) {
+    strengths.push('Well-defined customer segments')
+  } else if (segmentScore < 40) {
+    weaknesses.push('Customer segments need more definition')
+  }
+
+  // Score value propositions
+  const valueScore = scoreValuePropositions(canvas.valuePropositions)
+  blockScores['valuePropositions'] = valueScore
+  if (valueScore >= 70) {
+    strengths.push('Strong value propositions')
+  } else if (valueScore < 40) {
+    weaknesses.push('Value propositions need strengthening')
+  }
+
+  // Score channels
+  const channelScore = scoreChannels(canvas.channels)
+  blockScores['channels'] = channelScore
+  if (channelScore >= 70) {
+    strengths.push('Diverse channel strategy')
+  } else if (channelScore < 40) {
+    weaknesses.push('Limited channel coverage')
+  }
+
+  // Score relationships
+  const relationshipScore = scoreRelationships(canvas.customerRelationships)
+  blockScores['customerRelationships'] = relationshipScore
+  if (relationshipScore >= 70) {
+    strengths.push('Strong customer relationship strategy')
+  } else if (relationshipScore < 40) {
+    weaknesses.push('Customer relationship strategy needs work')
+  }
+
+  // Score revenue streams
+  const revenueScore = scoreRevenueStreams(canvas.revenueStreams)
+  blockScores['revenueStreams'] = revenueScore
+  if (revenueScore >= 70) {
+    strengths.push('Solid revenue model')
+  } else if (revenueScore < 40) {
+    weaknesses.push('Revenue model needs development')
+  }
+
+  // Score resources
+  const resourceScore = scoreResources(canvas.keyResources)
+  blockScores['keyResources'] = resourceScore
+  if (resourceScore >= 70) {
+    strengths.push('Strong resource base')
+  } else if (resourceScore < 40) {
+    weaknesses.push('Key resources are lacking')
+  }
+
+  // Score activities
+  const activityScore = scoreActivities(canvas.keyActivities)
+  blockScores['keyActivities'] = activityScore
+  if (activityScore >= 70) {
+    strengths.push('Clear key activities')
+  } else if (activityScore < 40) {
+    weaknesses.push('Key activities need clarification')
+  }
+
+  // Score partnerships
+  const partnershipScore = scorePartnerships(canvas.keyPartnerships)
+  blockScores['keyPartnerships'] = partnershipScore
+  if (partnershipScore >= 70) {
+    strengths.push('Strong partnership ecosystem')
+  } else if (partnershipScore < 40) {
+    weaknesses.push('Partnership strategy needs development')
+  }
+
+  // Score cost structure
+  const costScore = scoreCostStructure(canvas.costStructure)
+  blockScores['costStructure'] = costScore
+  if (costScore >= 70) {
+    strengths.push('Well-understood cost structure')
+  } else if (costScore < 40) {
+    weaknesses.push('Cost structure needs more detail')
+  }
+
+  // Calculate overall score
+  const scores = Object.values(blockScores)
+  const overallScore = scores.reduce((sum, s) => sum + s, 0) / scores.length
+
+  return {
+    overallScore,
+    strengths,
+    weaknesses,
+    blockScores,
+  }
+}
+
+/**
+ * Identify gaps in the canvas
+ */
+export function identifyCanvasGaps(canvas: BusinessModelCanvas): CanvasGaps {
+  const criticalGaps: string[] = []
+  const warnings: string[] = []
+  const recommendations: string[] = []
+
+  // Check for critical gaps (empty building blocks)
+  if (canvas.valuePropositions.length === 0) {
+    criticalGaps.push('valuePropositions')
+    recommendations.push('Define at least one clear value proposition for your target customers')
+  }
+
+  if (canvas.customerSegments.length === 0) {
+    criticalGaps.push('customerSegments')
+    recommendations.push('Identify and define your target customer segments')
+  }
+
+  if (canvas.revenueStreams.length === 0) {
+    criticalGaps.push('revenueStreams')
+    recommendations.push('Define how you will generate revenue from your customers')
+  }
+
+  if (canvas.customerRelationships.length === 0) {
+    criticalGaps.push('customerRelationships')
+    recommendations.push('Define how you will acquire, retain, and grow customer relationships')
+  }
+
+  if (canvas.keyResources.length === 0) {
+    criticalGaps.push('keyResources')
+    recommendations.push('Identify the key resources required to deliver your value proposition')
+  }
+
+  if (canvas.keyActivities.length === 0) {
+    criticalGaps.push('keyActivities')
+    recommendations.push('Define the key activities required to operate your business')
+  }
+
+  if (canvas.keyPartnerships.length === 0) {
+    criticalGaps.push('keyPartnerships')
+    recommendations.push('Consider strategic partnerships that could enhance your business')
+  }
+
+  if (canvas.channels.length === 0) {
+    criticalGaps.push('channels')
+    recommendations.push('Define channels to reach and serve your customers')
+  }
+
+  if (canvas.costStructure.length === 0) {
+    criticalGaps.push('costStructure')
+    recommendations.push('Map out your cost structure to understand your business economics')
+  }
+
+  // Check for warnings (incomplete data)
+  const hasRecurringRevenue = canvas.revenueStreams.some(r => r.type === 'recurring')
+  if (!hasRecurringRevenue && canvas.revenueStreams.length > 0) {
+    warnings.push('No recurring revenue streams - consider subscription or usage-based models')
+    recommendations.push('Explore recurring revenue models for more predictable cash flow')
+  }
+
+  const hasIntellectualProperty = canvas.keyResources.some(r => r.type === 'intellectual')
+  if (!hasIntellectualProperty && canvas.keyResources.length > 0) {
+    warnings.push('No intellectual property identified - consider what makes your offering unique')
+    recommendations.push('Identify and protect your intellectual property assets')
+  }
+
+  return {
+    criticalGaps,
+    warnings,
+    recommendations,
+  }
+}
+
+// =============================================================================
+// Helper scoring functions
+// =============================================================================
+
+function scoreCustomerSegments(segments: CustomerSegment[]): number {
+  if (segments.length === 0) return 0
+  let score = 30 // Base score for having segments
+
+  // Add points for segment details
+  const hasSize = segments.some(s => s.size)
+  const hasRevenue = segments.some(s => s.revenuePerCustomer)
+  const hasCharacteristics = segments.some(s => s.characteristics && s.characteristics.length > 0)
+
+  if (hasSize) score += 20
+  if (hasRevenue) score += 25
+  if (hasCharacteristics) score += 15
+
+  // Bonus for multiple segments
+  if (segments.length >= 2) score += 10
+
+  return Math.min(score, 100)
+}
+
+function scoreValuePropositions(props: ValueProposition[]): number {
+  if (props.length === 0) return 0
+  let score = 30
+
+  const hasBenefits = props.some(p => p.benefits.length >= 2)
+  const hasValueType = props.some(p => p.valueType)
+  const hasSegmentFit = props.some(p => p.segmentFit)
+  const hasQuantified = props.some(p => p.quantifiedValue)
+
+  if (hasBenefits) score += 20
+  if (hasValueType) score += 15
+  if (hasSegmentFit) score += 20
+  if (hasQuantified) score += 15
+
+  return Math.min(score, 100)
+}
+
+function scoreChannels(channels: Channel[]): number {
+  if (channels.length === 0) return 0
+  let score = 30
+
+  const hasPhases = channels.some(c => c.phases && c.phases.length > 0)
+  const hasCost = channels.some(c => c.costPerAcquisition)
+  const hasMultipleTypes = new Set(channels.map(c => c.type)).size >= 2
+
+  if (hasPhases) score += 20
+  if (hasCost) score += 25
+  if (hasMultipleTypes) score += 25
+
+  return Math.min(score, 100)
+}
+
+function scoreRelationships(relationships: CustomerRelationship[]): number {
+  if (relationships.length === 0) return 0
+  let score = 40
+
+  const hasAutomation = relationships.some(r => r.automationLevel)
+  const hasSegment = relationships.some(r => r.segment)
+  const hasMultipleTypes = new Set(relationships.map(r => r.type)).size >= 2
+
+  if (hasAutomation) score += 20
+  if (hasSegment) score += 20
+  if (hasMultipleTypes) score += 20
+
+  return Math.min(score, 100)
+}
+
+function scoreRevenueStreams(streams: RevenueStream[]): number {
+  if (streams.length === 0) return 0
+  let score = 30
+
+  const hasRecurring = streams.some(s => s.type === 'recurring')
+  const hasPrice = streams.some(s => s.price || s.pricePerUnit)
+  const hasCustomers = streams.some(s => s.activeCustomers)
+  const hasTiers = streams.some(s => s.tiers && s.tiers.length > 0)
+
+  if (hasRecurring) score += 25
+  if (hasPrice) score += 20
+  if (hasCustomers) score += 15
+  if (hasTiers) score += 10
+
+  return Math.min(score, 100)
+}
+
+function scoreResources(resources: KeyResource[]): number {
+  if (resources.length === 0) return 0
+  let score = 30
+
+  const hasIntellectual = resources.some(r => r.type === 'intellectual')
+  const hasHuman = resources.some(r => r.type === 'human')
+  const hasCost = resources.some(r => r.totalCost || r.cost)
+  const hasMultipleTypes = new Set(resources.map(r => r.type)).size >= 2
+
+  if (hasIntellectual) score += 20
+  if (hasHuman) score += 15
+  if (hasCost) score += 20
+  if (hasMultipleTypes) score += 15
+
+  return Math.min(score, 100)
+}
+
+function scoreActivities(activities: KeyActivity[]): number {
+  if (activities.length === 0) return 0
+  let score = 40
+
+  const hasResources = activities.some(a => a.resources && a.resources.length > 0)
+  const hasMetrics = activities.some(a => a.metrics && a.metrics.length > 0)
+  const hasDescription = activities.some(a => a.description)
+
+  if (hasResources) score += 20
+  if (hasMetrics) score += 25
+  if (hasDescription) score += 15
+
+  return Math.min(score, 100)
+}
+
+function scorePartnerships(partnerships: KeyPartnership[]): number {
+  if (partnerships.length === 0) return 0
+  let score = 40
+
+  const hasBenefits = partnerships.some(p => p.benefits && p.benefits.length > 0)
+  const hasPurpose = partnerships.some(p => p.purpose)
+  const hasContract = partnerships.some(p => p.contractValue)
+
+  if (hasBenefits) score += 20
+  if (hasPurpose) score += 20
+  if (hasContract) score += 20
+
+  return Math.min(score, 100)
+}
+
+function scoreCostStructure(costs: CostItem[]): number {
+  if (costs.length === 0) return 0
+  let score = 30
+
+  const hasFixed = costs.some(c => c.category === 'fixed')
+  const hasVariable = costs.some(c => c.category === 'variable')
+  const hasAmounts = costs.some(c => c.amount || c.estimatedTotal)
+  const hasPeriod = costs.some(c => c.period)
+
+  if (hasFixed) score += 15
+  if (hasVariable) score += 20
+  if (hasAmounts) score += 25
+  if (hasPeriod) score += 10
+
+  return Math.min(score, 100)
+}

package/src/canvas/channels.ts

@@ -0,0 +1,34 @@
+/**
+ * Channels
+ *
+ * Functions for creating and working with channels.
+ */
+
+import type { Channel, ChannelType, ChannelPhase } from './types.js'
+
+export interface CreateChannelInput {
+  name: string
+  type: ChannelType
+  phases?: ChannelPhase[]
+  costPerAcquisition?: number
+  partnerType?: string
+  revenueShare?: number
+  conversionRate?: number
+}
+
+/**
+ * Create a channel
+ */
+export function createChannel(input: CreateChannelInput): Channel {
+  const { name, type, phases, costPerAcquisition, partnerType, revenueShare, conversionRate } = input
+
+  return {
+    name,
+    type,
+    phases,
+    costPerAcquisition,
+    partnerType,
+    revenueShare,
+    conversionRate,
+  }
+}