Best Practices for Business-as-Code

my-business/
├── src/
│   ├── business/           # Business entity definitions
│   │   ├── organization.ts
│   │   ├── products.ts
│   │   └── customers.ts
│   ├── workflows/          # Business workflows
│   │   ├── order-processing.ts
│   │   ├── customer-onboarding.ts
│   │   └── inventory-management.ts
│   ├── agents/             # Autonomous agents
│   │   ├── sales-agent.ts
│   │   ├── support-agent.ts
│   │   └── operations-agent.ts
│   ├── functions/          # Reusable business functions
│   │   ├── pricing.ts
│   │   ├── notifications.ts
│   │   └── analytics.ts
│   ├── integrations/       # External system integrations
│   │   ├── stripe.ts
│   │   ├── sendgrid.ts
│   │   └── shopify.ts
│   ├── schema/             # Data models and types
│   │   ├── types.ts
│   │   └── validations.ts
│   └── utils/              # Utility functions
│       ├── logger.ts
│       ├── retry.ts
│       └── cache.ts
├── tests/                  # Test files
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── config/                 # Configuration
│   ├── development.ts
│   ├── staging.ts
│   └── production.ts
├── docs/                   # Documentation
└── scripts/                # Build and deployment scripts

// src/business/products.ts
import $, { db } from 'sdk.do'

export class ProductModule {
  // Create product with validation
  async create(data: ProductInput) {
    const product = await $.Product.create({
      ...data,
      $type: 'Product',
      dateCreated: new Date(),
      productionDate: new Date(),
    })

    return product
  }

  // Update pricing
  async updatePrice(productId: string, newPrice: number) {
    return db.Products.update(productId, {
      offers: [
        {
          $type: 'Offer',
          price: newPrice,
          priceCurrency: 'USD',
          priceValidUntil: this.calculatePriceExpiry(),
        },
      ],
    })
  }

  // Product catalog operations
  async addToCategory(productId: string, categoryId: string) {
    return db.relate(productId, $.belongsTo, categoryId)
  }

  private calculatePriceExpiry() {
    const expiry = new Date()
    expiry.setDate(expiry.getDate() + 30)
    return expiry
  }
}

// src/functions/pricing.ts
import { ai } from 'sdk.do'

// Small, focused functions
export const calculateBasePrice = (cost: number, margin: number): number => {
  return cost * (1 + margin)
}

export const applyDiscount = (price: number, discount: number): number => {
  return price * (1 - discount)
}

export const roundToNearest = (price: number, nearest: number): number => {
  return Math.round(price / nearest) * nearest
}

// Compose into higher-level function
export const calculateFinalPrice = async (cost: number, margin: number, customerTier: string) => {
  // Base calculation
  const basePrice = calculateBasePrice(cost, margin)

  // AI-driven discount
  const discount = await ai.decide('customer-discount', {
    tier: customerTier,
    basePrice,
  })

  // Apply discount and round
  const discountedPrice = applyDiscount(basePrice, discount.percentage)
  return roundToNearest(discountedPrice, 0.99)
}

// src/workflows/order-processing.ts
import $, { on, send, db } from 'sdk.do'

export class OrderProcessingWorkflow {
  async initialize() {
    // Register event handlers
    on($.Order.created, this.handleOrderCreated.bind(this))
    on($.Payment.completed, this.handlePaymentCompleted.bind(this))
    on($.Order.fulfilled, this.handleOrderFulfilled.bind(this))
  }

  private async handleOrderCreated(order: Order) {
    // Validate order
    const validation = await this.validateOrder(order)
    if (!validation.valid) {
      await send($.Order.cancel, { order, reason: validation.reason })
      return
    }

    // Process payment
    await send($.Payment.process, {
      order,
      amount: order.totalPrice,
      method: order.paymentMethod,
    })
  }

  private async handlePaymentCompleted(payment: Payment) {
    const order = await db.related(payment, $.forOrder, $.Order)

    // Update inventory
    await send($.Inventory.reserve, {
      items: order.orderedItem,
    })

    // Schedule fulfillment
    await send($.Order.fulfill, { order })
  }

  private async handleOrderFulfilled(order: Order) {
    // Send confirmation
    await send($.Email.send, {
      to: order.customer.email,
      template: 'order-shipped',
      data: { order },
    })

    // Update analytics
    await send($.Analytics.track, {
      event: 'order_completed',
      properties: { orderId: order.$id, revenue: order.totalPrice },
    })
  }

  private async validateOrder(order: Order): Promise<ValidationResult> {
    // Validate inventory
    for (const item of order.orderedItem) {
      const available = await db.query($.Product, {
        $id: item.orderedItem.$id,
        'quantityAvailable:gte': item.orderQuantity,
      })

      if (!available) {
        return {
          valid: false,
          reason: `Insufficient inventory for ${item.orderedItem.name}`,
        }
      }
    }

    return { valid: true }
  }
}

// src/agents/sales-agent.ts
import $, { ai, db, send } from 'sdk.do'

export class SalesAgent {
  private context: AgentContext

  constructor(config: AgentConfig) {
    this.context = {
      businessId: config.businessId,
      personality: config.personality || 'professional',
      knowledgeBase: config.knowledgeBase,
    }
  }

  // Handle customer inquiry
  async handleInquiry(inquiry: CustomerInquiry): Promise<Response> {
    // Understand intent
    const intent = await ai.classify({
      text: inquiry.message,
      categories: ['product_question', 'pricing', 'support', 'sales'],
    })

    // Route to appropriate handler
    switch (intent.category) {
      case 'product_question':
        return this.answerProductQuestion(inquiry)
      case 'pricing':
        return this.providePricing(inquiry)
      case 'sales':
        return this.handleSalesOpportunity(inquiry)
      default:
        return this.handoffToSupport(inquiry)
    }
  }

  private async answerProductQuestion(inquiry: CustomerInquiry) {
    // Retrieve relevant products
    const products = await db.search($.Product, {
      query: inquiry.message,
      limit: 3,
    })

    // Generate response
    const response = await ai.generate({
      model: 'gpt-5',
      prompt: `Answer customer question about products`,
      context: {
        question: inquiry.message,
        products,
        personality: this.context.personality,
      },
    })

    return {
      message: response.text,
      suggestedProducts: products,
      followUpActions: response.actions,
    }
  }

  private async handleSalesOpportunity(inquiry: CustomerInquiry) {
    // Create lead
    const lead = await $.Lead.create({
      customer: inquiry.customer,
      source: 'chat',
      inquiry: inquiry.message,
      assignedTo: 'sales-agent',
    })

    // Qualify lead
    const qualification = await ai.decide('lead-qualification', {
      lead,
      customer: inquiry.customer,
    })

    if (qualification.score > 0.7) {
      // High-quality lead - engage immediately
      await send($.Meeting.schedule, {
        lead,
        type: 'discovery_call',
      })
    }

    return {
      message: qualification.response,
      nextSteps: qualification.actions,
    }
  }
}

// src/utils/errors.ts

// Base error class
export class BusinessError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number = 500,
    public retryable: boolean = false,
    public metadata?: Record<string, any>
  ) {
    super(message)
    this.name = this.constructor.name
    Error.captureStackTrace(this, this.constructor)
  }
}

// Specific error types
export class ValidationError extends BusinessError {
  constructor(message: string, metadata?: Record<string, any>) {
    super(message, 'VALIDATION_ERROR', 400, false, metadata)
  }
}

export class ResourceNotFoundError extends BusinessError {
  constructor(resource: string, id: string) {
    super(`${resource} with id ${id} not found`, 'RESOURCE_NOT_FOUND', 404, false, { resource, id })
  }
}

export class ExternalServiceError extends BusinessError {
  constructor(service: string, originalError: Error) {
    super(`External service ${service} failed: ${originalError.message}`, 'EXTERNAL_SERVICE_ERROR', 502, true, {
      service,
      originalError: originalError.message,
    })
  }
}

export class RateLimitError extends BusinessError {
  constructor(retryAfter: number) {
    super('Rate limit exceeded', 'RATE_LIMIT_EXCEEDED', 429, true, { retryAfter })
  }
}

// src/utils/retry.ts

interface RetryOptions {
  maxAttempts?: number
  baseDelay?: number
  maxDelay?: number
  backoffMultiplier?: number
  retryableErrors?: string[]
  onRetry?: (error: Error, attempt: number) => void
}

export const withRetry = async <T>(operation: () => Promise<T>, options: RetryOptions = {}): Promise<T> => {
  const {
    maxAttempts = 3,
    baseDelay = 1000,
    maxDelay = 30000,
    backoffMultiplier = 2,
    retryableErrors = ['EXTERNAL_SERVICE_ERROR', 'RATE_LIMIT_EXCEEDED'],
    onRetry,
  } = options

  let lastError: Error

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await operation()
    } catch (error) {
      lastError = error as Error

      // Check if error is retryable
      const isRetryable = error instanceof BusinessError && error.retryable && retryableErrors.includes(error.code)

      if (!isRetryable || attempt === maxAttempts) {
        throw error
      }

      // Calculate delay with exponential backoff
      const delay = Math.min(baseDelay * Math.pow(backoffMultiplier, attempt - 1), maxDelay)

      // Add jitter to prevent thundering herd
      const jitter = delay * 0.1 * Math.random()
      const totalDelay = delay + jitter

      onRetry?.(error, attempt)

      await new Promise((resolve) => setTimeout(resolve, totalDelay))
    }
  }

  throw lastError!
}

// Usage example
export const callExternalAPI = async (endpoint: string, data: any) => {
  return withRetry(
    async () => {
      const response = await fetch(endpoint, {
        method: 'POST',
        body: JSON.stringify(data),
      })

      if (!response.ok) {
        throw new ExternalServiceError(endpoint, new Error(response.statusText))
      }

      return response.json()
    },
    {
      maxAttempts: 3,
      onRetry: (error, attempt) => {
        console.log(`Retry attempt ${attempt} after error: ${error.message}`)
      },
    }
  )
}

// src/utils/fallback.ts
import { ai } from 'sdk.do'

export const withFallback = async <T>(
  primary: () => Promise<T>,
  fallback: () => Promise<T>,
  options: {
    timeout?: number
    onFallback?: (error: Error) => void
  } = {}
): Promise<T> => {
  const { timeout = 5000, onFallback } = options

  try {
    // Try primary operation with timeout
    return await Promise.race([primary(), new Promise<never>((_, reject) => setTimeout(() => reject(new Error('Operation timeout')), timeout))])
  } catch (error) {
    onFallback?.(error as Error)
    return fallback()
  }
}

// Example: AI with fallback to rule-based system
export const classifyCustomerIntent = async (message: string) => {
  return withFallback(
    // Primary: AI classification
    async () => {
      return ai.classify({
        text: message,
        categories: ['question', 'complaint', 'sales', 'support'],
      })
    },
    // Fallback: Rule-based classification
    async () => {
      const lowerMessage = message.toLowerCase()

      if (lowerMessage.includes('buy') || lowerMessage.includes('purchase')) {
        return { category: 'sales', confidence: 0.6 }
      }
      if (lowerMessage.includes('problem') || lowerMessage.includes('issue')) {
        return { category: 'complaint', confidence: 0.6 }
      }
      if (lowerMessage.includes('how') || lowerMessage.includes('?')) {
        return { category: 'question', confidence: 0.6 }
      }

      return { category: 'support', confidence: 0.5 }
    },
    {
      onFallback: (error) => {
        console.warn('AI classification failed, using rule-based fallback:', error)
      },
    }
  )
}

// src/utils/error-reporter.ts

interface ErrorContext {
  userId?: string
  businessId?: string
  operation?: string
  metadata?: Record<string, any>
}

class ErrorReporter {
  private static instance: ErrorReporter

  static getInstance(): ErrorReporter {
    if (!ErrorReporter.instance) {
      ErrorReporter.instance = new ErrorReporter()
    }
    return ErrorReporter.instance
  }

  async report(error: Error, context: ErrorContext = {}) {
    // Log to console
    console.error('Error occurred:', {
      error: {
        name: error.name,
        message: error.message,
        stack: error.stack,
      },
      context,
      timestamp: new Date().toISOString(),
    })

    // Send to monitoring service
    await this.sendToMonitoring(error, context)

    // Store in database for analysis
    await this.storeError(error, context)

    // Alert if critical
    if (this.isCritical(error)) {
      await this.sendAlert(error, context)
    }
  }

  private async sendToMonitoring(error: Error, context: ErrorContext) {
    // Send to Sentry, Datadog, etc.
    try {
      await fetch(process.env.MONITORING_ENDPOINT!, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          error: {
            message: error.message,
            stack: error.stack,
            type: error.name,
          },
          context,
          timestamp: Date.now(),
        }),
      })
    } catch (monitoringError) {
      // Don't fail the application if monitoring fails
      console.error('Failed to send error to monitoring:', monitoringError)
    }
  }

  private async storeError(error: Error, context: ErrorContext) {
    const { db } = await import('sdk.do')

    try {
      await db.create('$.ErrorLog', {
        $type: 'ErrorLog',
        errorType: error.name,
        message: error.message,
        stack: error.stack,
        context,
        timestamp: new Date(),
      })
    } catch (dbError) {
      console.error('Failed to store error in database:', dbError)
    }
  }

  private isCritical(error: Error): boolean {
    return error instanceof BusinessError && (error.code === 'DATABASE_ERROR' || error.code === 'PAYMENT_ERROR' || error.statusCode >= 500)
  }

  private async sendAlert(error: Error, context: ErrorContext) {
    const { send } = await import('sdk.do')

    await send('$.Alert.send', {
      severity: 'critical',
      title: `Critical error: ${error.name}`,
      message: error.message,
      context,
    })
  }
}

export const reportError = ErrorReporter.getInstance().report.bind(ErrorReporter.getInstance())

// src/workflows/recovery.ts
import $, { on, send, db } from 'sdk.do'

export class RecoveryWorkflow {
  async initialize() {
    // Monitor failed operations
    on($.Operation.failed, this.handleFailedOperation.bind(this))
  }

  private async handleFailedOperation(operation: Operation) {
    const recoveryStrategy = this.determineRecoveryStrategy(operation)

    switch (recoveryStrategy) {
      case 'retry':
        await this.retryOperation(operation)
        break
      case 'compensate':
        await this.compensateOperation(operation)
        break
      case 'manual':
        await this.escalateToHuman(operation)
        break
    }
  }

  private determineRecoveryStrategy(operation: Operation): RecoveryStrategy {
    if (operation.retryCount < 3 && operation.error?.retryable) {
      return 'retry'
    }

    if (operation.compensatable) {
      return 'compensate'
    }

    return 'manual'
  }

  private async retryOperation(operation: Operation) {
    await send($.Operation.retry, {
      operationId: operation.$id,
      attempt: operation.retryCount + 1,
    })
  }

  private async compensateOperation(operation: Operation) {
    // Execute compensating transaction
    const compensationSteps = await this.getCompensationSteps(operation)

    for (const step of compensationSteps) {
      await send(step.action, step.params)
    }

    // Mark as compensated
    await db.update('$.Operation', operation.$id, {
      status: 'compensated',
      compensatedAt: new Date(),
    })
  }

  private async escalateToHuman(operation: Operation) {
    await send('$.Task.create', {
      $type: 'Task',
      title: `Manual intervention required: ${operation.name}`,
      description: `Operation ${operation.$id} failed and requires manual review`,
      priority: 'high',
      assignedTo: 'operations-team',
      metadata: {
        operationId: operation.$id,
        error: operation.error,
      },
    })
  }
}

// tests/unit/pricing.test.ts
import { describe, it, expect, vi } from 'vitest'
import { calculateFinalPrice, calculateBasePrice } from '@/functions/pricing'
import { ai } from 'sdk.do'

describe('Pricing Functions', () => {
  describe('calculateBasePrice', () => {
    it('should calculate base price with margin', () => {
      expect(calculateBasePrice(100, 0.5)).toBe(150)
    })

    it('should handle zero margin', () => {
      expect(calculateBasePrice(100, 0)).toBe(100)
    })
  })

  describe('calculateFinalPrice', () => {
    it('should calculate final price with AI discount', async () => {
      // Mock AI decision
      vi.spyOn(ai, 'decide').mockResolvedValue({
        percentage: 0.1,
      })

      const finalPrice = await calculateFinalPrice(100, 0.5, 'premium')

      // Base: 150, Discount 10%: 135, Rounded: 134.99
      expect(finalPrice).toBe(134.99)
      expect(ai.decide).toHaveBeenCalledWith('customer-discount', {
        tier: 'premium',
        basePrice: 150,
      })
    })

    it('should handle AI failure gracefully', async () => {
      vi.spyOn(ai, 'decide').mockRejectedValue(new Error('AI service down'))

      await expect(calculateFinalPrice(100, 0.5, 'premium')).rejects.toThrow('AI service down')
    })
  })
})

// tests/integration/order-processing.test.ts
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
import { OrderProcessingWorkflow } from '@/workflows/order-processing'
import $, { db, send } from 'sdk.do'

describe('Order Processing Workflow', () => {
  let workflow: OrderProcessingWorkflow
  let testOrder: Order

  beforeEach(async () => {
    workflow = new OrderProcessingWorkflow()
    await workflow.initialize()

    // Create test data
    testOrder = await $.Order.create({
      customer: await $.Customer.create({ email: '[email protected]' }),
      orderedItem: [
        {
          $type: 'OrderItem',
          orderedItem: await $.Product.create({ name: 'Test Product', quantityAvailable: 10 }),
          orderQuantity: 2,
        },
      ],
      totalPrice: 100,
      paymentMethod: 'credit_card',
    })
  })

  afterEach(async () => {
    // Cleanup test data
    await db.delete('$.Order', testOrder.$id)
  })

  it('should process order successfully', async () => {
    // Trigger order created event
    await send('$.Order.created', testOrder)

    // Wait for processing
    await new Promise((resolve) => setTimeout(resolve, 1000))

    // Verify payment was processed
    const payments = await db.related(testOrder, '$.hasPayment', '$.Payment')
    expect(payments).toHaveLength(1)
    expect(payments[0].status).toBe('completed')

    // Verify inventory was reserved
    const product = testOrder.orderedItem[0].orderedItem
    const updatedProduct = await db.get('$.Product', product.$id)
    expect(updatedProduct.quantityAvailable).toBe(8)
  })

  it('should cancel order if validation fails', async () => {
    // Create order with insufficient inventory
    const invalidOrder = await $.Order.create({
      customer: await $.Customer.create({ email: '[email protected]' }),
      orderedItem: [
        {
          $type: 'OrderItem',
          orderedItem: await $.Product.create({ name: 'Low Stock', quantityAvailable: 1 }),
          orderQuantity: 10,
        },
      ],
      totalPrice: 100,
    })

    await send('$.Order.created', invalidOrder)
    await new Promise((resolve) => setTimeout(resolve, 1000))

    const order = await db.get('$.Order', invalidOrder.$id)
    expect(order.status).toBe('cancelled')
  })
})

// tests/e2e/sales-agent.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest'
import { SalesAgent } from '@/agents/sales-agent'
import { db } from 'sdk.do'

describe('Sales Agent E2E', () => {
  let agent: SalesAgent
  let testBusiness: Business

  beforeAll(async () => {
    // Setup test environment
    testBusiness = await db.create('$.Organization', {
      name: 'Test Business',
    })

    agent = new SalesAgent({
      businessId: testBusiness.$id,
      personality: 'professional',
    })
  })

  afterAll(async () => {
    // Cleanup
    await db.delete('$.Organization', testBusiness.$id)
  })

  it('should handle product inquiry end-to-end', async () => {
    const inquiry = {
      customer: await db.create('$.Customer', {
        email: '[email protected]',
      }),
      message: 'Tell me about your premium subscription',
      channel: 'chat',
    }

    const response = await agent.handleInquiry(inquiry)

    expect(response.message).toBeTruthy()
    expect(response.suggestedProducts).toBeInstanceOf(Array)
    expect(response.followUpActions).toBeDefined()
  })

  it('should create and qualify leads', async () => {
    const inquiry = {
      customer: await db.create('$.Customer', {
        email: '[email protected]',
        company: 'Enterprise Corp',
      }),
      message: 'We need enterprise solution for 100+ users',
      channel: 'chat',
    }

    const response = await agent.handleInquiry(inquiry)

    // Verify lead was created
    const leads = await db.query('$.Lead', {
      'customer.$id': inquiry.customer.$id,
    })
    expect(leads).toHaveLength(1)
    expect(leads[0].source).toBe('chat')

    // Verify meeting was scheduled for high-quality lead
    const meetings = await db.related(leads[0], '$.hasMeeting', '$.Meeting')
    expect(meetings.length).toBeGreaterThan(0)
  })
})

// tests/fixtures/mock-data.ts
import $ from 'sdk.do'

export const mockCustomer = (overrides = {}) => ({
  $type: 'Customer',
  email: '[email protected]',
  name: 'Mock Customer',
  dateCreated: new Date(),
  ...overrides,
})

export const mockProduct = (overrides = {}) => ({
  $type: 'Product',
  name: 'Mock Product',
  description: 'A test product',
  offers: [
    {
      $type: 'Offer',
      price: 99.99,
      priceCurrency: 'USD',
    },
  ],
  quantityAvailable: 100,
  ...overrides,
})

export const mockOrder = (overrides = {}) => ({
  $type: 'Order',
  customer: mockCustomer(),
  orderedItem: [
    {
      $type: 'OrderItem',
      orderedItem: mockProduct(),
      orderQuantity: 1,
    },
  ],
  totalPrice: 99.99,
  orderStatus: 'pending',
  ...overrides,
})

// Test data builder
export class TestDataBuilder {
  private data: any = {}

  customer(overrides = {}) {
    this.data.customer = mockCustomer(overrides)
    return this
  }

  product(overrides = {}) {
    if (!this.data.products) this.data.products = []
    this.data.products.push(mockProduct(overrides))
    return this
  }

  order(overrides = {}) {
    this.data.order = mockOrder({
      customer: this.data.customer,
      orderedItem: this.data.products?.map((p) => ({
        $type: 'OrderItem',
        orderedItem: p,
        orderQuantity: 1,
      })),
      ...overrides,
    })
    return this
  }

  build() {
    return this.data
  }
}

// Usage
const testData = new TestDataBuilder()
  .customer({ email: '[email protected]' })
  .product({ name: 'Premium Widget', quantityAvailable: 5 })
  .product({ name: 'Basic Widget', quantityAvailable: 50 })
  .order({ totalPrice: 199.98 })
  .build()

# .github/workflows/test.yml
name: Test Suite

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v2

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install

      - name: Run unit tests
        run: pnpm test:unit --coverage

      - name: Run integration tests
        run: pnpm test:integration
        env:
          DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}

      - name: Run E2E tests
        run: pnpm test:e2e
        env:
          API_KEY: ${{ secrets.TEST_API_KEY }}

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage/coverage-final.json

  quality:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup
        uses: pnpm/action-setup@v2

      - name: Lint
        run: pnpm lint

      - name: Type check
        run: pnpm typecheck

      - name: Check formatting
        run: pnpm format:check

// Inefficient: Multiple database calls
async function getOrderDetails(orderId: string) {
  const order = await db.get('$.Order', orderId)
  const customer = await db.get('$.Customer', order.customer.$id)
  const products = await Promise.all(order.orderedItem.map((item) => db.get('$.Product', item.orderedItem.$id)))

  return { order, customer, products }
}

// Efficient: Single query with includes
async function getOrderDetailsOptimized(orderId: string) {
  const order = await db.get('$.Order', orderId, {
    include: [
      'customer',
      'orderedItem.orderedItem', // Include nested products
    ],
  })

  return {
    order,
    customer: order.customer,
    products: order.orderedItem.map((item) => item.orderedItem),
  }
}

// Efficient: Batch operations
async function updateProductPrices(updates: Array<{ id: string; price: number }>) {
  // Inefficient: Loop with individual updates
  // for (const update of updates) {
  //   await db.update('$.Product', update.id, { price: update.price })
  // }

  // Efficient: Batch update
  await db.batchUpdate(
    '$.Product',
    updates.map((u) => ({
      $id: u.id,
      offers: [{ $type: 'Offer', price: u.price, priceCurrency: 'USD' }],
    }))
  )
}

// src/workflows/optimized-processing.ts
import $, { on, send, db } from 'sdk.do'

export class OptimizedWorkflow {
  async initialize() {
    on($.Order.created, this.handleOrderCreated.bind(this))
  }

  private async handleOrderCreated(order: Order) {
    // Inefficient: Sequential operations
    // await send($.Payment.process, { order })
    // await send($.Inventory.reserve, { order })
    // await send($.Email.send, { to: order.customer.email })

    // Efficient: Parallel independent operations
    await Promise.all([
      send($.Payment.process, { order }),
      send($.Inventory.reserve, { order }),
      send($.Email.send, {
        to: order.customer.email,
        template: 'order-confirmation',
      }),
      send($.Analytics.track, {
        event: 'order_created',
        properties: { orderId: order.$id },
      }),
    ])
  }

  // Use streaming for large data sets
  private async processLargeInventoryUpdate(productIds: string[]) {
    // Inefficient: Load all products into memory
    // const products = await db.query('$.Product', { $id: { $in: productIds } })
    // for (const product of products) { ... }

    // Efficient: Stream processing
    const stream = db.stream('$.Product', { $id: { $in: productIds } })

    for await (const product of stream) {
      await this.updateProduct(product)
      // Memory is freed after each iteration
    }
  }
}

// src/agents/optimized-agent.ts
import { ai, db } from 'sdk.do'

export class OptimizedAgent {
  private cache = new Map<string, CachedResponse>()
  private requestQueue: RequestQueue

  constructor() {
    // Implement request batching
    this.requestQueue = new RequestQueue({
      maxBatchSize: 10,
      maxWaitMs: 100,
    })
  }

  async processInquiry(inquiry: string): Promise<Response> {
    // Check cache first
    const cached = this.cache.get(inquiry)
    if (cached && !this.isCacheExpired(cached)) {
      return cached.response
    }

    // Batch AI requests
    const response = await this.requestQueue.add(async (batch) => {
      // Process multiple inquiries in single AI call
      return ai.generate({
        model: 'gpt-5',
        prompt: 'Answer customer inquiries',
        context: { inquiries: batch },
      })
    })

    // Cache result
    this.cache.set(inquiry, {
      response,
      timestamp: Date.now(),
      ttl: 3600000, // 1 hour
    })

    return response
  }

  // Implement context pruning for long conversations
  private async pruneContext(context: Message[]): Promise<Message[]> {
    if (context.length <= 10) return context

    // Keep first message (system context) and last 9 messages
    return [context[0], ...context.slice(-9)]
  }

  // Lazy load knowledge base
  private knowledgeBase: KnowledgeBase | null = null

  private async getKnowledgeBase(): Promise<KnowledgeBase> {
    if (!this.knowledgeBase) {
      this.knowledgeBase = await db.get('$.KnowledgeBase', this.config.knowledgeBaseId)
    }
    return this.knowledgeBase
  }
}

// src/utils/cache.ts

interface CacheOptions {
  ttl?: number
  prefix?: string
}

class CacheManager {
  private memoryCache = new Map<string, CachedValue>()
  private redis: RedisClient // Distributed cache

  constructor(redisClient: RedisClient) {
    this.redis = redisClient
  }

  // L1: Memory cache (fastest, instance-local)
  private async getFromMemory(key: string): Promise<any | null> {
    const cached = this.memoryCache.get(key)

    if (!cached) return null

    if (Date.now() > cached.expiry) {
      this.memoryCache.delete(key)
      return null
    }

    return cached.value
  }

  // L2: Redis cache (fast, distributed)
  private async getFromRedis(key: string): Promise<any | null> {
    const cached = await this.redis.get(key)

    if (!cached) return null

    const parsed = JSON.parse(cached)

    // Populate L1 cache
    this.memoryCache.set(key, {
      value: parsed.value,
      expiry: parsed.expiry,
    })

    return parsed.value
  }

  // Get with automatic fallback through cache levels
  async get<T>(key: string, fetcher: () => Promise<T>, options: CacheOptions = {}): Promise<T> {
    const fullKey = options.prefix ? `${options.prefix}:${key}` : key

    // Try L1 cache
    let value = await this.getFromMemory(fullKey)
    if (value !== null) return value

    // Try L2 cache
    value = await this.getFromRedis(fullKey)
    if (value !== null) return value

    // Fetch from source
    value = await fetcher()

    // Populate all cache levels
    await this.set(fullKey, value, options)

    return value
  }

  async set(key: string, value: any, options: CacheOptions = {}) {
    const ttl = options.ttl || 3600000 // Default 1 hour
    const expiry = Date.now() + ttl

    // Set L1 cache
    this.memoryCache.set(key, { value, expiry })

    // Set L2 cache
    await this.redis.setex(key, Math.floor(ttl / 1000), JSON.stringify({ value, expiry }))
  }

  async invalidate(pattern: string) {
    // Clear from memory
    for (const key of this.memoryCache.keys()) {
      if (key.match(pattern)) {
        this.memoryCache.delete(key)
      }
    }

    // Clear from Redis
    const keys = await this.redis.keys(pattern)
    if (keys.length > 0) {
      await this.redis.del(...keys)
    }
  }
}

// Usage example
const cache = new CacheManager(redisClient)

export const getProductWithCache = async (productId: string) => {
  return cache.get(
    productId,
    async () => {
      // This only runs if cache miss
      return db.get('$.Product', productId)
    },
    {
      ttl: 300000, // 5 minutes
      prefix: 'product',
    }
  )
}

// Invalidate cache on updates
export const updateProduct = async (productId: string, data: Partial<Product>) => {
  const updated = await db.update('$.Product', productId, data)

  // Invalidate related caches
  await cache.invalidate(`product:${productId}`)
  await cache.invalidate('product-list:*')

  return updated
}

// src/utils/database-optimization.ts
import { db } from 'sdk.do'

// Use indexes effectively
export const setupIndexes = async () => {
  await db.createIndex('$.Order', ['customer.$id', 'orderDate'])
  await db.createIndex('$.Product', ['category', 'price'])
  await db.createIndex('$.Customer', ['email']) // Unique index
}

// Efficient pagination
export const paginateOrders = async (page: number, pageSize: number = 20) => {
  // Inefficient: Load all and slice
  // const all = await db.query('$.Order', {})
  // return all.slice(page * pageSize, (page + 1) * pageSize)

  // Efficient: Database-level pagination
  return db.query('$.Order', {
    $sort: { orderDate: -1 },
    $skip: page * pageSize,
    $limit: pageSize,
  })
}

// Use projections to reduce data transfer
export const getOrderList = async () => {
  // Inefficient: Fetch all fields
  // const orders = await db.query('$.Order', {})

  // Efficient: Fetch only needed fields
  return db.query('$.Order', {
    $select: ['$id', 'orderNumber', 'totalPrice', 'orderDate', 'orderStatus'],
  })
}

// Aggregate in database
export const getOrderStatistics = async (customerId: string) => {
  // Inefficient: Fetch all orders and calculate in code
  // const orders = await db.query('$.Order', { 'customer.$id': customerId })
  // const total = orders.reduce((sum, o) => sum + o.totalPrice, 0)

  // Efficient: Database aggregation
  const [stats] = await db.aggregate('$.Order', [
    { $match: { 'customer.$id': customerId } },
    {
      $group: {
        _id: '$customer.$id',
        totalOrders: { $sum: 1 },
        totalRevenue: { $sum: '$totalPrice' },
        averageOrderValue: { $avg: '$totalPrice' },
      },
    },
  ])

  return stats
}

// Implement read replicas for heavy read workloads
export const getProductCatalog = async () => {
  // Use read replica for queries that don't need strong consistency
  return db.query(
    '$.Product',
    {},
    {
      readPreference: 'secondary',
    }
  )
}

// src/utils/rate-limiter.ts

interface RateLimitConfig {
  maxRequests: number
  windowMs: number
  keyGenerator?: (context: any) => string
}

export class RateLimiter {
  private requests = new Map<string, number[]>()

  constructor(private config: RateLimitConfig) {}

  async checkLimit(context: any): Promise<boolean> {
    const key = this.config.keyGenerator?.(context) || 'global'
    const now = Date.now()
    const windowStart = now - this.config.windowMs

    // Get existing requests within window
    const existing = this.requests.get(key) || []
    const validRequests = existing.filter((time) => time > windowStart)

    // Check limit
    if (validRequests.length >= this.config.maxRequests) {
      throw new RateLimitError(Math.ceil((validRequests[0] + this.config.windowMs - now) / 1000))
    }

    // Add new request
    validRequests.push(now)
    this.requests.set(key, validRequests)

    return true
  }

  async reset(context: any) {
    const key = this.config.keyGenerator?.(context) || 'global'
    this.requests.delete(key)
  }
}

// Usage: Rate limit by customer
const customerRateLimiter = new RateLimiter({
  maxRequests: 100,
  windowMs: 60000, // 1 minute
  keyGenerator: (ctx) => ctx.customerId,
})

export const handleCustomerRequest = async (customerId: string, request: any) => {
  await customerRateLimiter.checkLimit({ customerId })

  // Process request
  return processRequest(request)
}

// Usage: Rate limit AI operations
const aiRateLimiter = new RateLimiter({
  maxRequests: 10,
  windowMs: 60000,
  keyGenerator: (ctx) => `ai:${ctx.operation}`,
})

export const generateAIResponse = async (operation: string, prompt: string) => {
  await aiRateLimiter.checkLimit({ operation })

  return ai.generate({ model: 'gpt-5', prompt })
}

// src/security/auth.ts
import { db } from 'sdk.do'
import bcrypt from 'bcrypt'
import jwt from 'jsonwebtoken'

export class AuthService {
  private jwtSecret = process.env.JWT_SECRET!
  private jwtExpiry = '24h'

  // User registration
  async register(email: string, password: string): Promise<User> {
    // Validate password strength
    this.validatePassword(password)

    // Hash password
    const hashedPassword = await bcrypt.hash(password, 12)

    // Create user
    const user = await db.create('$.Person', {
      $type: 'Person',
      email,
      hashedPassword,
      emailVerified: false,
      createdAt: new Date(),
    })

    // Send verification email
    await this.sendVerificationEmail(user)

    return user
  }

  // User login
  async login(email: string, password: string): Promise<AuthToken> {
    // Find user
    const [user] = await db.query('$.Person', { email })

    if (!user) {
      throw new ValidationError('Invalid credentials')
    }

    // Verify password
    const valid = await bcrypt.compare(password, user.hashedPassword)

    if (!valid) {
      throw new ValidationError('Invalid credentials')
    }

    // Check if email is verified
    if (!user.emailVerified) {
      throw new ValidationError('Email not verified')
    }

    // Generate tokens
    const accessToken = this.generateAccessToken(user)
    const refreshToken = this.generateRefreshToken(user)

    // Store refresh token
    await db.update('$.Person', user.$id, {
      refreshToken,
      lastLoginAt: new Date(),
    })

    return {
      accessToken,
      refreshToken,
      expiresIn: this.jwtExpiry,
    }
  }

  // Verify token
  async verifyToken(token: string): Promise<User> {
    try {
      const decoded = jwt.verify(token, this.jwtSecret) as { userId: string }

      const user = await db.get('$.Person', decoded.userId)

      if (!user) {
        throw new Error('User not found')
      }

      return user
    } catch (error) {
      throw new ValidationError('Invalid token')
    }
  }

  private generateAccessToken(user: User): string {
    return jwt.sign(
      {
        userId: user.$id,
        email: user.email,
        roles: user.roles || [],
      },
      this.jwtSecret,
      { expiresIn: this.jwtExpiry }
    )
  }

  private generateRefreshToken(user: User): string {
    return jwt.sign({ userId: user.$id, type: 'refresh' }, this.jwtSecret, { expiresIn: '30d' })
  }

  private validatePassword(password: string) {
    if (password.length < 8) {
      throw new ValidationError('Password must be at least 8 characters')
    }

    if (!/[A-Z]/.test(password)) {
      throw new ValidationError('Password must contain uppercase letter')
    }

    if (!/[a-z]/.test(password)) {
      throw new ValidationError('Password must contain lowercase letter')
    }

    if (!/[0-9]/.test(password)) {
      throw new ValidationError('Password must contain number')
    }
  }

  private async sendVerificationEmail(user: User) {
    const token = jwt.sign({ userId: user.$id, type: 'verification' }, this.jwtSecret, { expiresIn: '24h' })

    await send('$.Email.send', {
      to: user.email,
      template: 'email-verification',
      data: {
        verificationLink: `https://app.do/verify?token=${token}`,
      },
    })
  }
}

// src/security/encryption.ts
import crypto from 'crypto'

export class EncryptionService {
  private algorithm = 'aes-256-gcm'
  private keyLength = 32
  private ivLength = 16

  constructor(private masterKey: string) {
    if (masterKey.length !== this.keyLength) {
      throw new Error('Master key must be 32 characters')
    }
  }

  // Encrypt data
  encrypt(plaintext: string): EncryptedData {
    // Generate random IV
    const iv = crypto.randomBytes(this.ivLength)

    // Create cipher
    const cipher = crypto.createCipheriv(this.algorithm, Buffer.from(this.masterKey), iv)

    // Encrypt
    let encrypted = cipher.update(plaintext, 'utf8', 'hex')
    encrypted += cipher.final('hex')

    // Get auth tag
    const authTag = cipher.getAuthTag()

    return {
      encrypted,
      iv: iv.toString('hex'),
      authTag: authTag.toString('hex'),
    }
  }

  // Decrypt data
  decrypt(encryptedData: EncryptedData): string {
    // Create decipher
    const decipher = crypto.createDecipheriv(this.algorithm, Buffer.from(this.masterKey), Buffer.from(encryptedData.iv, 'hex'))

    // Set auth tag
    decipher.setAuthTag(Buffer.from(encryptedData.authTag, 'hex'))

    // Decrypt
    let decrypted = decipher.update(encryptedData.encrypted, 'hex', 'utf8')
    decrypted += decipher.final('utf8')

    return decrypted
  }

  // Hash data (one-way)
  hash(data: string): string {
    return crypto.createHash('sha256').update(data).digest('hex')
  }
}

// Usage: Encrypt sensitive customer data
const encryption = new EncryptionService(process.env.MASTER_KEY!)

export const createCustomerWithSensitiveData = async (data: CustomerData) => {
  // Encrypt SSN
  const encryptedSSN = data.ssn ? encryption.encrypt(data.ssn) : null

  // Encrypt credit card
  const encryptedCC = data.creditCard ? encryption.encrypt(data.creditCard) : null

  return db.create('$.Customer', {
    ...data,
    ssn: encryptedSSN,
    creditCard: encryptedCC,
    ssnHash: data.ssn ? encryption.hash(data.ssn) : null, // For lookup without decryption
  })
}

// src/security/api-keys.ts
import { db } from 'sdk.do'
import crypto from 'crypto'

export class APIKeyService {
  // Generate API key
  async generateKey(name: string, permissions: string[], expiresIn?: number): Promise<APIKeyResult> {
    // Generate random key
    const key = `sk_${crypto.randomBytes(32).toString('hex')}`

    // Hash key for storage
    const hashedKey = crypto.createHash('sha256').update(key).digest('hex')

    // Calculate expiry
    const expiresAt = expiresIn ? new Date(Date.now() + expiresIn) : null

    // Store key metadata
    await db.create('$.APIKey', {
      $type: 'APIKey',
      name,
      hashedKey,
      permissions,
      expiresAt,
      createdAt: new Date(),
      lastUsedAt: null,
      usageCount: 0,
    })

    // Return plain key (only shown once)
    return {
      key,
      name,
      permissions,
      expiresAt,
    }
  }

  // Validate API key
  async validateKey(key: string): Promise<APIKeyData | null> {
    const hashedKey = crypto.createHash('sha256').update(key).digest('hex')

    const [apiKey] = await db.query('$.APIKey', { hashedKey })

    if (!apiKey) {
      return null
    }

    // Check expiry
    if (apiKey.expiresAt && new Date() > apiKey.expiresAt) {
      return null
    }

    // Update usage
    await db.update('$.APIKey', apiKey.$id, {
      lastUsedAt: new Date(),
      usageCount: apiKey.usageCount + 1,
    })

    return {
      $id: apiKey.$id,
      permissions: apiKey.permissions,
      name: apiKey.name,
    }
  }

  // Revoke API key
  async revokeKey(keyId: string) {
    await db.update('$.APIKey', keyId, {
      revokedAt: new Date(),
    })
  }

  // Rotate API key
  async rotateKey(oldKeyId: string): Promise<APIKeyResult> {
    const oldKey = await db.get('$.APIKey', oldKeyId)

    // Generate new key
    const newKey = await this.generateKey(oldKey.name, oldKey.permissions, oldKey.expiresAt ? oldKey.expiresAt.getTime() - Date.now() : undefined)

    // Revoke old key
    await this.revokeKey(oldKeyId)

    return newKey
  }
}

// Middleware: Verify API key
export const requireAPIKey = (requiredPermissions: string[] = []) => {
  return async (context: Context) => {
    const authHeader = context.req.header('Authorization')

    if (!authHeader?.startsWith('Bearer ')) {
      throw new ValidationError('Missing API key')
    }

    const key = authHeader.substring(7)
    const apiKeyService = new APIKeyService()
    const apiKey = await apiKeyService.validateKey(key)

    if (!apiKey) {
      throw new ValidationError('Invalid API key')
    }

    // Check permissions
    for (const permission of requiredPermissions) {
      if (!apiKey.permissions.includes(permission)) {
        throw new ValidationError(`Missing permission: ${permission}`)
      }
    }

    // Add to context
    context.set('apiKey', apiKey)
  }
}

// src/security/rbac.ts
import { db } from 'sdk.do'

export enum Permission {
  // Product permissions
  PRODUCT_CREATE = 'product:create',
  PRODUCT_READ = 'product:read',
  PRODUCT_UPDATE = 'product:update',
  PRODUCT_DELETE = 'product:delete',

  // Order permissions
  ORDER_CREATE = 'order:create',
  ORDER_READ = 'order:read',
  ORDER_UPDATE = 'order:update',
  ORDER_CANCEL = 'order:cancel',

  // Customer permissions
  CUSTOMER_READ = 'customer:read',
  CUSTOMER_UPDATE = 'customer:update',

  // Admin permissions
  ADMIN_ALL = 'admin:*',
}

export const Roles = {
  admin: [Permission.ADMIN_ALL],
  manager: [
    Permission.PRODUCT_CREATE,
    Permission.PRODUCT_READ,
    Permission.PRODUCT_UPDATE,
    Permission.ORDER_READ,
    Permission.ORDER_UPDATE,
    Permission.CUSTOMER_READ,
  ],
  sales: [Permission.PRODUCT_READ, Permission.ORDER_CREATE, Permission.ORDER_READ, Permission.CUSTOMER_READ, Permission.CUSTOMER_UPDATE],
  support: [Permission.PRODUCT_READ, Permission.ORDER_READ, Permission.CUSTOMER_READ],
  customer: [Permission.ORDER_CREATE, Permission.ORDER_READ],
}

export class RBACService {
  // Check if user has permission
  async checkPermission(userId: string, permission: Permission): Promise<boolean> {
    const user = await db.get('$.Person', userId)

    if (!user.roles || user.roles.length === 0) {
      return false
    }

    // Admin has all permissions
    if (user.roles.includes('admin')) {
      return true
    }

    // Check role permissions
    for (const role of user.roles) {
      const permissions = Roles[role] || []

      if (permissions.includes(Permission.ADMIN_ALL)) {
        return true
      }

      if (permissions.includes(permission)) {
        return true
      }
    }

    return false
  }

  // Assign role to user
  async assignRole(userId: string, role: string) {
    const user = await db.get('$.Person', userId)
    const roles = user.roles || []

    if (!roles.includes(role)) {
      await db.update('$.Person', userId, {
        roles: [...roles, role],
      })
    }
  }

  // Remove role from user
  async removeRole(userId: string, role: string) {
    const user = await db.get('$.Person', userId)
    const roles = user.roles || []

    await db.update('$.Person', userId, {
      roles: roles.filter((r) => r !== role),
    })
  }
}

// Middleware: Require permission
export const requirePermission = (permission: Permission) => {
  return async (context: Context) => {
    const user = context.get('user')

    if (!user) {
      throw new ValidationError('Authentication required')
    }

    const rbac = new RBACService()
    const hasPermission = await rbac.checkPermission(user.$id, permission)

    if (!hasPermission) {
      throw new ValidationError(`Missing permission: ${permission}`)
    }
  }
}

// Usage in routes
import { Hono } from 'hono'

const app = new Hono()

app.post('/products', requirePermission(Permission.PRODUCT_CREATE), async (c) => {
  // Create product
  const product = await $.Product.create(await c.req.json())
  return c.json(product)
})

app.delete('/products/:id', requirePermission(Permission.PRODUCT_DELETE), async (c) => {
  await db.delete('$.Product', c.req.param('id'))
  return c.json({ success: true })
})

// src/security/audit.ts
import { db } from 'sdk.do'

export enum AuditAction {
  USER_LOGIN = 'user.login',
  USER_LOGOUT = 'user.logout',
  USER_REGISTER = 'user.register',
  PASSWORD_CHANGE = 'password.change',
  ROLE_ASSIGNED = 'role.assigned',
  PERMISSION_GRANTED = 'permission.granted',
  DATA_ACCESS = 'data.access',
  DATA_MODIFY = 'data.modify',
  DATA_DELETE = 'data.delete',
  API_KEY_CREATED = 'api_key.created',
  API_KEY_REVOKED = 'api_key.revoked',
}

export class AuditLogger {
  async log(
    action: AuditAction,
    actor: { type: 'user' | 'system' | 'api_key'; id: string },
    target?: { type: string; id: string },
    metadata?: Record<string, any>
  ) {
    await db.create('$.AuditLog', {
      $type: 'AuditLog',
      action,
      actor,
      target,
      metadata,
      timestamp: new Date(),
      ipAddress: metadata?.ipAddress,
      userAgent: metadata?.userAgent,
    })
  }

  async query(filters: AuditLogFilters) {
    return db.query('$.AuditLog', {
      ...filters,
      $sort: { timestamp: -1 },
    })
  }
}

// Usage
const audit = new AuditLogger()

export const loginWithAudit = async (email: string, password: string, metadata: any) => {
  const authService = new AuthService()

  try {
    const result = await authService.login(email, password)

    // Log successful login
    await audit.log(AuditAction.USER_LOGIN, { type: 'user', id: result.user.$id }, undefined, {
      success: true,
      ipAddress: metadata.ipAddress,
      userAgent: metadata.userAgent,
    })

    return result
  } catch (error) {
    // Log failed login attempt
    await audit.log(AuditAction.USER_LOGIN, { type: 'user', id: email }, undefined, {
      success: false,
      error: error.message,
      ipAddress: metadata.ipAddress,
      userAgent: metadata.userAgent,
    })

    throw error
  }
}