Files · Perplexity Security Guardrails for QuickBooks Online Invoice Processing

# Perplexity Security Guardrails for QuickBooks Online Invoice Processing
 
> Wrap every Perplexity‑powered invoice classification with PII redaction, financial policy enforcement, and full audit trails — so SMBs safely automate QuickBooks Online workflows.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Architecture
 
```
┌──────────────┐    ┌──────────────────┐    ┌────────────────┐    ┌──────────────────┐    ┌──────────────────────┐
│   Input      │ →  │   Perplexity     │ →  │   Output       │ →  │   Output         │ →  │   QuickBooks         │
│  Guardrails  │    │   API            │    │   Repair       │    │   Guardrails     │    │   Online Write‑back  │
│              │    │                  │    │                │    │                  │    │                      │
│ • PII        │    │ /chat/completion │    │ • Schema       │    │ • Financial      │    │ • invoice POST       │
│   redaction  │    │   (classification│    │   validation   │    │   policy check   │    │ • error logging      │
│ • Input      │    │    + extraction) │    │ • Type         │    │ • Budget cap     │    │ • audit trail        │
│   validation │    │                  │    │   coercion     │    │ • Audit record   │    │                      │
└──────────────┘    └──────────────────┘    └────────────────┘    └──────────────────┘    └──────────────────────┘
```
 
All stages emit OpenTelemetry spans and Langfuse traces. Cost telemetry is captured per-LLM-call via `@reaatech/llm-cost-telemetry`.
 
## Setup
 
### Prerequisites
 
- Node.js >= 22
- pnpm 10
- Perplexity API key
- QuickBooks Online sandbox account (Intuit Developer account)
- Langfuse account (optional, for observability)
- OTLP-compatible telemetry backend (optional)
 
### Environment variables
 
Copy `.env.example` to `.env` and fill in your values:
 
```bash
cp .env.example .env
```
 
Key variables:
 
| Variable | Description |
|---|---|
| `PERPLEXITY_API_KEY` | Your Perplexity API key |
| `QBO_CLIENT_ID` | Intuit OAuth 2.0 client ID |
| `QBO_CLIENT_SECRET` | Intuit OAuth 2.0 client secret |
| `QBO_ENVIRONMENT` | `sandbox` or `production` |
| `QBO_COMPANY_ID` | QuickBooks Online company ID |
| `LANGFUSE_SECRET_KEY` | Langfuse API secret |
| `DEFAULT_DAILY_BUDGET` | Cost budget per feature per day |
 
### Install & run
 
```bash
pnpm install
pnpm dev             # next dev — http://localhost:3000
pnpm test            # vitest run with coverage
pnpm typecheck       # tsc --noEmit
pnpm lint            # eslint .
```
 
## API
 
### POST /api/process-invoice
 
Classify an invoice line item.
 
**Request body:**
 
```json
{
  "invoiceId": "123",
  "companyId": "456",
  "prompt": "Categorize this invoice for accounting purposes"
}
```
 
**Response:**
 
```json
{
  "classification": { "category": "uncategorized", "confidence": 0 },
  "invoice": {
    "Id": "123",
    "CustomerRef": { "name": "Unknown", "value": "456" },
    "Line": [],
    "TotalAmt": 0
  },
  "auditTraceId": "audit-1719000000000",
  "budget": {
    "tenant": "456",
    "dailyBudgetUsd": 5.0,
    "dailySpentUsd": 0,
    "remainingDailyUsd": 5.0,
    "lastResetDate": "2026-06-21"
  },
  "message": "Invoice 123 processed for company 456"
}
```
 
### GET /api/admin/violations
 
Returns guardrail policy violations for audit.
 
**Response:**
 
```json
{
  "violations": [
    {
      "guardrail": "budget-cap",
      "input": { "description": "Laptop", "amount": 5000 },
      "reason": "Exceeds single-transaction limit of $3000",
      "timestamp": "2026-06-21T12:00:00Z"
    }
  ],
  "totalCount": 1
}
```
 
### GET /api/admin/budget
 
Returns current cost telemetry and budget status.
 
**Response:**
 
```json
{
  "dailyBudget": 5.00,
  "spentToday": 1.23,
  "remaining": 3.77,
  "feature": "invoice-classification"
}
```
 
## Testing
 
The test suite uses [vitest](https://vitest.dev) with [MSW](https://mswjs.io) for HTTP mocking:
 
```bash
pnpm test                      # full suite with coverage
pnpm vitest run                # without coverage
pnpm vitest --watch            # watch mode
```
 
Test infrastructure:
 
- `tests/setup.ts` — MSW server lifecycle (auto-starts before all tests, resets between tests, closes after all)
- `tests/mocks/handlers.ts` — reusable MSW request handlers for Perplexity, QuickBooks, and Langfuse
- `tests/mocks/fixtures.ts` — reusable mock objects (invoice, classification, guardrail result, cost span)
 
## Package listing
 
### `@reaatech/*` packages
 
| Package | Description |
|---|---|
| [`@reaatech/guardrail-chain`](packages/reaatech__guardrail-chain.md) | Orchestrates guardrail pipeline stages with configurable chains |
| [`@reaatech/guardrail-chain-config`](packages/reaatech__guardrail-chain-config.md) | Type-safe configuration loader for guardrail chains |
| [`@reaatech/guardrail-chain-guardrails`](packages/reaatech__guardrail-chain-guardrails.md) | Built-in guardrail implementations (PII, financial policy, budget) |
| [`@reaatech/guardrail-chain-observability`](packages/reaatech__guardrail-chain-observability.md) | OpenTelemetry + Langfuse instrumentation for guardrail chains |
| [`@reaatech/llm-cost-telemetry`](packages/reaatech__llm-cost-telemetry.md) | Per-LLM-call cost tracking with daily budget enforcement |
| [`@reaatech/structured-repair-core`](packages/reaatech__structured-repair-core.md) | Schema validation and type coercion for LLM structured outputs |
 
### Third-party packages
 
| Package | Description |
|---|---|
| [`next`](https://nextjs.org) | React framework for server-rendered APIs and UI |
| [`perplexity-sdk`](packages/perplexity-sdk.md) | Perplexity AI chat completions API client |
| [`intuit-oauth`](packages/intuit-oauth.md) | Intuit OAuth 2.0 client for QuickBooks Online |
| [`langfuse`](packages/langfuse.md) | LLM observability and tracing platform |
| [`@opentelemetry/api`](packages/opentelemetry__api.md) | OpenTelemetry API for distributed tracing |
| [`@opentelemetry/sdk-node`](packages/opentelemetry__sdk-node.md) | OpenTelemetry Node.js SDK |
| [`@presidio-dev/hai-guardrails`](packages/presidio-dev__hai-guardrails.md) | Guardrails SDK for content safety and PII detection |
| [`zod`](packages/zod.md) | TypeScript-first schema validation |
| [`p-retry`](packages/p-retry.md) | Retry utility for async operations |
 
## License
 
MIT — see [LICENSE](./LICENSE).