business-as-code 0.1.0 → 0.2.1

package/README.md

@@ -7,228 +7,255 @@
 
 ## Overview
 
-`business-as-code` enables organizations to represent their businesses and processes in code for human-AI collaboration. Unlike `ai-business` which focuses on AI-only businesses, this package provides interfaces for integrating human roles, AI agents, and defining collaboration points between them.
+`business-as-code` provides a schema-first approach to defining business entities. Write your business model in MDX, YAML, or JSON, and use it across different platforms.
+
+```
+business-as-code (portable schema layer)
+       ↓
+   ┌───┴───┐
+   ↓       ↓
+Startups.Studio    Platform.do
+(AI startups)      (Enterprise)
+```
+
+This is the **schema definition layer** - it defines what your business entities look like. It works alongside runtime packages like [agents.do](https://agents.do), [workflows.do](https://workflows.do), and [humans.do](https://humans.do) which handle the actual business operations.
 
 ## Installation
 
 ```bash
 npm install business-as-code
 # or
-yarn add business-as-code
-# or
 pnpm add business-as-code
 ```
 
-## Usage
+## Quick Start
 
-### Creating a Business with Human-AI Collaboration
+### Use the Default Business Schema
 
-```typescript
-import { Business } from 'business-as-code'
-import { Human } from 'humans.do'
-import { Agent } from 'agents.do'
-import { Workflow } from 'workflows.do'
-
-// Create human roles
-class CEO extends Human {}
-class CTO extends Human {}
-class MarketingManager extends Human {}
-
-// Create AI agents
-class DataAnalyst extends Agent {}
-class CustomerSupportAgent extends Agent {}
-
-// Create business processes
-class CustomerOnboarding extends Workflow {}
-class ProductDevelopment extends Workflow {}
-
-// Define your business
-const myCompany = Business({
-  name: 'Acme Corporation',
-  url: 'https://acme.com',
-  vision: 'To revolutionize industry X with innovative solutions',
-  goals: [
-    {
-      objective: 'Increase market share by 20%',
-      keyResults: ['Launch 3 new products', 'Expand to 2 new geographical markets', 'Increase customer retention by 15%'],
-    },
-  ],
-  // Human roles
-  roles: {
-    ceo: CEO,
-    cto: CTO,
-    marketingManager: MarketingManager,
-  },
-  // AI agents
-  agents: {
-    dataAnalyst: DataAnalyst,
-    customerSupport: CustomerSupportAgent,
-  },
-  // Organizational structure
-  departments: {
-    engineering: {
-      name: 'Engineering Department',
-      lead: CTO,
-      members: [DataAnalyst],
-    },
-    marketing: {
-      name: 'Marketing Department',
-      lead: MarketingManager,
-      members: [],
-    },
-  },
-  // Business processes
-  processes: {
-    customerOnboarding: CustomerOnboarding,
-    productDevelopment: ProductDevelopment,
-  },
-})
-
-// Event handling
-myCompany.on('new_customer', (data) => {
-  // Trigger customer onboarding workflow
-  console.log(`New customer: ${data.name}`)
-})
-
-// Scheduled operations
-myCompany.every('day', () => {
-  // Daily operations
-  console.log('Performing daily operations')
-})
-
-// Task assignment
-myCompany.assign('Analyze quarterly sales data', myCompany.agents.dataAnalyst)
-myCompany.assign('Review marketing strategy', myCompany.roles.marketingManager)
-
-// Track business metrics
-myCompany.track('customer_satisfaction', 4.8)
-myCompany.track('monthly_revenue', 125000)
-```
+The package includes a comprehensive default schema with 40+ business entities across 9 domains:
 
-## Differences from `ai-business`
+```typescript
+import { defaultBusinessSchema, getAllNouns } from 'business-as-code'
 
-While `ai-business` focuses on AI-driven business functions, `business-as-code` is designed specifically for representing existing organizations with both human employees and AI agents:
+// Get all nouns from the default business schema
+const nouns = getAllNouns(defaultBusinessSchema)
+console.log(`${nouns.length} nouns loaded`)
 
-| Feature              | business-as-code                   | ai-business                    |
-| -------------------- | ---------------------------------- | ------------------------------ |
-| Primary focus        | Human-AI collaboration             | AI-driven business functions   |
-| Organizational model | Comprehensive (roles, departments) | Limited (focused on functions) |
-| Human roles          | Explicit role definitions          | Not specifically modeled       |
-| Decision approval    | Built-in approval workflows        | Automated decision making      |
-| Task assignment      | Supports both humans and AI        | Primarily AI-focused           |
-| Integration          | Designed for existing org systems  | Standalone AI capabilities     |
+// Access specific noun schemas directly
+import { Customers, Products, Invoices, Projects, Teams } from 'business-as-code'
+```
 
-## Key Design Considerations
+### Define Custom Business in MDX
 
-### 1. Organizational hierarchy
+MDX provides the most expressive way to define business entities with JSX-like syntax:
 
 ```typescript
-// Define departments with reporting lines
-const company = Business({
-  departments: {
-    engineering: {
-      name: 'Engineering',
-      lead: CTO,
-      members: [SeniorEngineer, JuniorEngineer, AICodeReviewer],
-    },
-  },
-})
+import { loadFromMDX, mergeSchemas, defaultBusinessSchema } from 'business-as-code'
+
+const mdx = `
+<Business name="My SaaS">
+  <Noun name="Tenant" group="Admin">
+    <Name text required />
+    <Subdomain text unique />
+    <Plan status="free|pro|enterprise" />
+    <Owner user />
+  </Noun>
+
+  <Noun name="Feature" group="Product">
+    <Name text required />
+    <Description rich />
+    <Tier status="free|pro|enterprise" />
+    <Enabled boolean />
+  </Noun>
+</Business>
+`
+
+const customSchema = await loadFromMDX(mdx)
+const fullSchema = mergeSchemas(defaultBusinessSchema, customSchema)
 ```
 
-### 2. Human-AI collaboration points
+### Define Custom Business in YAML
+
+YAML is ideal for configuration files and version control:
 
 ```typescript
-// AI can suggest changes that require human approval
-company.on('content_suggestion', (suggestion, approver) => {
-  // Request approval from human
-  approver.requestApproval(suggestion)
-})
+import { loadFromYAML } from 'business-as-code'
+
+const yaml = `
+name: My SaaS
+version: 1.0.0
+
+domains:
+  admin:
+    - name: Tenant
+      titleField: name
+      fields:
+        name: text required
+        subdomain: text unique
+        plan: status:free|pro|enterprise
+        owner: ref:users
+
+  product:
+    - name: Feature
+      titleField: name
+      fields:
+        name: text required
+        description: rich
+        tier: status:free|pro|enterprise
+        enabled: boolean
+`
+
+const schema = loadFromYAML(yaml)
 ```
 
-### 3. Task assignment
+### Define Custom Business in JSON
+
+JSON works well for programmatic generation and API responses:
 
 ```typescript
-// Assign tasks based on nature and complexity
-function assignTask(task) {
-  if (task.requiresCreativity) {
-    company.assign(task, company.roles.humanCreative)
-  } else if (task.isRepetitive) {
-    company.assign(task, company.agents.automationAgent)
+import { loadFromJSON } from 'business-as-code'
+
+const json = {
+  name: "My SaaS",
+  version: "1.0.0",
+  domains: {
+    admin: [{
+      name: "Tenant",
+      titleField: "name",
+      fields: {
+        name: "text required",
+        subdomain: "text unique",
+        plan: "status:free|pro|enterprise"
+      }
+    }]
   }
 }
+
+const schema = loadFromJSON(JSON.stringify(json))
 ```
 
-### 4. Event handling differences
+## Domains
+
+The default business schema includes these domains:
+
+| Domain | Nouns | Description |
+|--------|-------|-------------|
+| **Admin** | Users, Orgs, ServiceAccounts | System administration |
+| **Business** | Businesses, Goals, Metrics, Teams, Processes | Core business entities |
+| **Product** | Products, Services, Offers, Prices, Features | Product catalog |
+| **Success** | Customers, Contacts, Subscriptions | Customer success |
+| **Sales** | Deals, Quotes, Proposals | Sales pipeline |
+| **Marketing** | Leads, Brands, Domains, Competitors | Marketing & branding |
+| **Work** | Projects, Tasks, Issues, Workflows, Roles, Agents | Work management |
+| **Financial** | Invoices, Payments, Refunds, ChartOfAccounts, JournalEntries | Accounting |
+| **Communications** | Channels, Messages, Sequences, Templates, Posts | Messaging |
+
+## Field Types
+
+### Primitive Types
+| Type | Description | Example |
+|------|-------------|---------|
+| `text` | Single-line text | `name: text` |
+| `rich` | Rich text / markdown | `description: rich` |
+| `number` | Numeric value | `count: number` |
+| `boolean` | True/false checkbox | `isActive: boolean` |
+| `date` | Date picker | `createdAt: date` |
+
+### Semantic Types (with validation)
+| Type | Description | Example |
+|------|-------------|---------|
+| `email` | Email address | `email: email` |
+| `url` | Valid URL | `website: url` |
+| `phone` | Phone number | `phone: phone` |
+| `slug` | URL-safe slug | `slug: slug` |
+
+### Business Types
+| Type | Description | Example |
+|------|-------------|---------|
+| `money` | Currency amount | `price: money` |
+| `score` | 0-100 value | `health: score` |
+| `status:a\|b\|c` | Select options | `status: status:active\|inactive` |
+
+### Relationship Types
+| Type | Description | Example |
+|------|-------------|---------|
+| `ref:collection` | Reference to another noun | `customer: ref:customers` |
+| `user` | Reference to users | `owner: user` |
+
+### Modifiers
+| Modifier | Description | Example |
+|----------|-------------|---------|
+| `required` | Field must have value | `name: text required` |
+| `unique` | Value must be unique | `slug: text unique` |
 
-```typescript
-// Human events may require notifications
-company.on('urgent_issue', (issue) => {
-  if (issue.assignee instanceof Human) {
-    sendNotification(issue.assignee)
-  } else {
-    // AI can handle immediately
-    issue.assignee.handle(issue)
-  }
-})
-```
+## API Reference
 
-### 5. Permission workflows
+### Schema Functions
 
 ```typescript
-// AI can draft but needs human approval for publishing
-company.agents.contentWriter.setPermission('content.publish', 'suggest')
-company.roles.contentManager.setPermission('content.publish', 'approve')
+import {
+  defaultBusinessSchema,  // The complete default schema
+  getAllNouns,           // Get all nouns as flat array
+  getDomainNouns,        // Get nouns for a specific domain
+  getDomains,            // Get list of all domain names
+  findNounBySlug,        // Find a noun by its slug
+  mergeSchemas,          // Merge two schemas together
+  validateSchema,        // Validate a schema structure
+  createMinimalSchema,   // Create empty schema scaffold
+} from 'business-as-code'
 ```
 
-### 6. System integration
+### Loaders
 
 ```typescript
-// Connect with existing organizational systems
-company.integrate('crm', {
-  endpoint: 'https://crm.company.com/api',
-  handlers: {
-    // Map events between systems
-    'crm:new_customer': (data) => company.trigger('new_customer', data),
-  },
-})
+import {
+  load,           // Auto-detect format and load
+  loadFromMDX,    // Load from MDX source
+  loadFromYAML,   // Load from YAML source
+  loadFromJSON,   // Load from JSON source
+  loadNoun,       // Load a single noun definition
+  loadNouns,      // Load multiple noun definitions
+} from 'business-as-code'
 ```
 
-### 7. Role guidelines
+### Serializers
 
 ```typescript
-// Define when to use humans vs AI
-const roleGuidelines = {
-  customer_complaints: {
-    simple: company.agents.customerSupport,
-    complex: company.roles.customerSuccessManager,
-    criteria: (complaint) => (complaint.sentiment < -0.8 ? 'complex' : 'simple'),
-  },
-}
+import {
+  serialize,      // Serialize schema to YAML or JSON
+  toYAML,         // Serialize to YAML string
+  toJSON,         // Serialize to JSON string
+  serializeNoun,  // Serialize single noun
+  nounToYAML,     // Noun to YAML
+  nounToJSON,     // Noun to JSON
+} from 'business-as-code'
 ```
 
-## API Reference
-
-### Functions
-
-- `Business(config)` - Creates a new business representation
-
 ### Types
 
-- `BusinessConfig` - Configuration for creating a business
-- `BusinessInstance` - Instance returned by the Business function
-- `PermissionLevel` - Enum for permission levels (VIEW, SUGGEST, EXECUTE, APPROVE, ADMIN)
-- `Task` - Interface for task assignments
-- `BusinessEvent` - Interface for business events
+```typescript
+import type {
+  BusinessSchema,    // Complete business schema
+  BusinessDomain,    // Domain name type
+  NounSchema,        // Individual noun definition
+  FieldSchema,       // Field definition
+  FieldType,         // Field type union
+  LoaderOptions,     // Options for loaders
+  LoadResult,        // Result from load operations
+} from 'business-as-code'
+```
+
+## Integration
 
-### Business Instance Methods
+`business-as-code` provides the schema layer that integrates with the broader .do ecosystem:
 
-- `on(event, handler)` - Register event handler
-- `every(schedule, operation)` - Register scheduled operation
-- `assign(task, to)` - Assign a task to a human or AI
-- `track(metric, value)` - Track business metrics
+- **[db.sb](https://db.sb)** - Database runtime that executes these schemas
+- **[Startups.Studio](https://startups.studio)** - AI-operated autonomous startups
+- **[Platform.do](https://platform.do)** - Enterprise business platform
+- **[agents.do](https://agents.do)** - AI agents for business operations
+- **[workflows.do](https://workflows.do)** - Business process automation
+- **[humans.do](https://humans.do)** - Human role definitions
 
-## Dependencies
+## License
 
-- [agents.do](https://github.com/drivly/agents.do) - Agent framework for AI operations
-- [humans.do](https://github.com/drivly/humans.do) - Human role definitions and interactions
-- [workflows.do](https://github.com/drivly/workflows.do) - Workflow definitions for business processes
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { a as BusinessDomain, b as BusinessExtension, B as BusinessSchema, F as FieldShorthand, c as LoadResult, L as LoaderOptions, N as NounShorthand } from './types-CJ9eGS_C.js';
+export { Agents, Brands, Businesses, Channels, ChartOfAccounts, Competitors, Contacts, Customers, Deals, Domains, Features, Goals, Invoices, Issues, JournalEntries, Leads, Messages, Metrics, Offers, Orgs, Payments, Posts, Prices, Processes, Products, Projects, Proposals, Quotes, Refunds, Roles, Sequences, ServiceAccounts, Services, Subscriptions, Tasks, Teams, Templates, Users, Workflows, adminNouns, businessNouns, communicationsNouns, createMinimalSchema, defaultBusinessSchema, financialNouns, findNounBySlug, getAllNouns, getDomainNouns, getDomains, marketingNouns, mergeSchemas, productNouns, salesNouns, successNouns, validateSchema, workNouns } from './schema/index.js';
+export { load, loadFromJSON, loadFromMDX, loadFromYAML, loadNoun, loadNounFromJSON, loadNounFromMDX, loadNounFromYAML, loadNouns, loadNounsFromJSON, loadNounsFromMDX, loadNounsFromYAML, nounToJSON, nounToYAML, serialize, serializeNoun, toJSON, toYAML } from './loaders/index.js';
+export { FieldSchema, FieldType, NounSchema } from 'db.sb';