# Clone the repository
git clone https://github.com/vespo92/QBO-MCP-TS.git
cd QBO-MCP-TS

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your QuickBooks credentials

# Build
npm run build

# Run
npm start

# QuickBooks OAuth
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
COMPANY_ID=your_company_id
REFRESH_TOKEN=your_refresh_token

# Environment
QBO_ENVIRONMENT=sandbox  # or 'production'
NODE_ENV=development

# SSE Transport (optional)
SSE_PORT=3100
SSE_HOST=localhost

# Webhook Receiver (optional)
WEBHOOK_PORT=3200
WEBHOOK_VERIFIER_TOKEN=your_webhook_token

# Cache Settings
CACHE_TTL=300
CACHE_MAX_SIZE=100
ENABLE_CACHE=true

# API Settings
RETRY_ATTEMPTS=3
RETRY_DELAY=1000
TIMEOUT=30000
RATE_LIMIT=60

# Redis (optional)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

{
  "tool": "create_invoice",
  "params": {
    "customerName": "Acme Corp",
    "items": [
      {
        "description": "Web Design Services",
        "amount": 2500,
        "quantity": 1
      },
      {
        "description": "Hosting (1 year)",
        "amount": 600,
        "quantity": 1
      }
    ],
    "dueDate": "net 30",
    "emailToCustomer": true
  }
}

{
  "tool": "get_invoices",
  "params": {
    "status": "overdue",
    "dateFrom": "this year",
    "dateTo": "today"
  }
}

{
  "tool": "get_profit_loss",
  "params": {
    "startDate": "this quarter",
    "endDate": "today",
    "accountingMethod": "Accrual",
    "summarizeBy": "Month"
  }
}

import { automationService } from './services/automation.service';

const scheduleId = await automationService.createRecurringInvoice({
  customerId: '123',
  lineItems: [
    { description: 'Monthly Retainer', amount: 5000 }
  ],
  frequency: 'monthly',
  startDate: new Date('2025-01-01'),
  dueInDays: 30,
  autoSend: true
});

import { workflowService } from './services/workflow.service';

workflowService.addRule({
  id: 'auto-approve-small-expenses',
  name: 'Auto-approve small expenses',
  enabled: true,
  trigger: 'expense:submitted',
  conditions: [
    { field: 'TotalAmt', operator: 'lt', value: 100 },
    { field: 'category', operator: 'in', value: ['Office Supplies'] }
  ],
  actions: [
    { type: 'approve', notify: 'submitter' },
    { type: 'broadcast_event', eventType: 'expense:auto_approved' }
  ]
});

import { getSSETransport } from './transports/sse.transport';

const sse = getSSETransport();
await sse.start();

// Events automatically broadcast:
// - invoice:created, invoice:updated, invoice:paid
// - payment:received
// - expense:created
// - customer:created
// - report:ready
// - webhook:received

import { getWebhookReceiver } from './webhooks/receiver';

const webhooks = getWebhookReceiver({
  port: 3200,
  verifierToken: process.env.WEBHOOK_VERIFIER_TOKEN
});

// Register handlers
webhooks.on('invoice:create', async (data) => {
  console.log('Invoice created:', data.id);
  // Cache invalidation, notifications, etc.
});

await webhooks.start();

import { multiCompanyService } from './services/multi-company.service';

// Add companies
await multiCompanyService.addCompany('company1', {
  name: 'Acme Corp',
  config: { /* QBO config */ }
});

await multiCompanyService.addCompany('company2', {
  name: 'XYZ Inc',
  config: { /* QBO config */ }
});

// Switch between companies
multiCompanyService.setActiveCompany('company1');
const invoices = await invoiceService.getInvoices();

multiCompanyService.setActiveCompany('company2');
const expenses = await expenseService.getExpenses();

import { createRedisCacheService } from './services/cache-redis.service';

const cache = await createRedisCacheService({
  host: 'localhost',
  port: 6379,
  keyPrefix: 'qbo:',
  enableFallback: true  // Falls back to in-memory if Redis unavailable
});

// Automatically used by all services

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

import { createMockInvoice, MockQBOApiClient } from './test-utils';

describe('InvoiceService', () => {
  it('should create invoice', async () => {
    const mockClient = new MockQBOApiClient();
    const service = new InvoiceService(mockClient);

    const invoice = await service.createInvoice({
      customerName: 'Test Customer',
      lineItems: [{ description: 'Test', amount: 100 }]
    });

    expect(invoice.Id).toBeDefined();
  });
});

{
  code: 'QBO_AUTH_001',
  message: 'Your QuickBooks session has expired',
  suggestion: 'Refreshing authentication automatically...',
  recoverable: true,
  severity: 'warning'
}