wulf-pulse/.planning/codebase/INTEGRATIONS.md

# External Integrations

**Analysis Date:** 2026-05-03

## APIs & External Services

**Autotask PSA:**
- Primary integration — syncs projects, tickets, time entries, contacts, configuration items to Postgres
- SDK/Client: `lib/services/autotask-factory.ts` → `getAutotaskClient()`, `lib/services/autotask-client.ts`
- Auth env vars: `AUTOTASK_API_URL`, `AUTOTASK_USERNAME`, `AUTOTASK_SECRET`, `AUTOTASK_API_INTEGRATION_CODE`
- Webhook secret: `AUTOTASK_WEBHOOK_SECRET` — HMAC-SHA1 verification in `lib/services/webhook-service.ts`
- Sync service: `lib/services/entity-sync.ts` (incremental via `lastTrackedModificationDateTime` when supported)
- Webhook handler: `/api/webhooks/autotask` (public endpoint)

**Microsoft Graph:**
- User/employee engagement data (calendar, presence, mail metrics)
- SDK/Client: `lib/services/msgraph-factory.ts` → `getMsgraphClient()`, `isMsgraphConfigured()`, `lib/services/msgraph-client.ts`
- Auth env vars: `MSGRAPH_CLIENT_ID`, `MSGRAPH_CLIENT_SECRET`, `MSGRAPH_TENANT_ID` (specific tenant, NOT 'common')
- Flow: client_credentials OAuth — no user interaction required
- Sync service: `lib/services/engagement-sync-service.ts`
- API: `/api/engagement/sync` (POST fire-and-forget, GET status), `/api/engagement/summary`, `/api/engagement/users`, `/api/engagement/user/[userId]`
- Scheduler: `engagement-daily` task (disabled by default, 6am UTC)

**Microsoft OAuth (Login):**
- SSO via Microsoft identity
- Auth env vars: `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET` (same as above; tenant-aware)
- Integrated into Better Auth 1.4 — `lib/auth.ts` configures `microsoft` social provider
- Account linking enabled: Microsoft OAuth can link to existing accounts

**Datto RMM:**
- Remote device management — sites, devices, alerts
- SDK/Client: `lib/services/datto-rmm-factory.ts` → `getDattoRMMClient()`, `lib/services/datto-rmm-client.ts`
- Auth env vars: `DATTO_RMM_API_URL`, `DATTO_RMM_API_KEY`, `DATTO_RMM_API_SECRET`
- Sync service: `lib/services/datto-rmm-sync-service.ts` (on-demand or scheduled)
- API: `/api/datto-rmm/sync` (public POST, fire-and-forget)
- Alternate simpler client: `lib/services/datto-rmm-client-simple.ts` available

**Veeam Backup & Replication:**
- Backup infrastructure data — sites, repositories, jobs, backup chains
- SDK/Client: `lib/services/veeam-factory.ts` → `getVeeamClient()`, `isVeeamConfigured()`, `lib/services/veeam-client.ts`
- Auth env vars: `VEEAM_VSPC_URL`, `VEEAM_VSPC_API_KEY`
- Shadow mode: `VEEAM_RPO_SHADOW_MODE=true` (default)
- Sync service: `lib/services/veeam-sync-service.ts`
- API: `/api/veeam/sync` (public POST), `/api/veeam/rpo-check` (public POST, RPO health check)

**Auvik:**
- Network monitoring — devices, interfaces, metrics
- SDK/Client: `lib/services/auvik-factory.ts` → `getAuvikClient()`, `lib/services/auvik-client.ts`
- Auth env vars: `AUVIK_API_URL`, `AUVIK_API_USER`, `AUVIK_API_KEY`

**Addigy:**
- Apple device management
- SDK/Client: `lib/services/addigy-factory.ts` → `getAddigyClient()`, `clearAddigyClientCache()`, `lib/services/addigy-client.ts`
- Auth env vars: `ADDIGY_API_URL` (default: `https://api.addigy.com/api/v2`), `ADDIGY_API_TOKEN`, `ADDIGY_ORG_ID` (optional)

**IT Glue:**
- Documentation platform — organizations, configurations, passwords, flexible assets
- SDK/Client: `lib/services/itglue-client.ts` (direct client, no factory)
- Auth env var: `ITGLUE_API_KEY` (x-api-key header)
- Base URL: `https://api.itglue.com`
- Format: JSON:API (application/vnd.api+json)
- Search function for analyzer: `lib/services/analyzer/itglue-search.ts` (redacted output before LLM prompts)
- Sync service: `lib/services/itglue-sync-service.ts`
- API: `/api/itglue/sync` (public POST, fire-and-forget)

**Mimecast:**
- Email security — threat/policy logs
- SDK/Client: `lib/services/mimecast-client.ts` (direct client, no factory)
- Auth env vars: `MIMECAST_CLIENT_ID`, `MIMECAST_CLIENT_SECRET`, `MIMECAST_ACCOUNT_CODE`, `MIMECAST_BASE_URL` (default: `https://api.services.mimecast.com`)

**SentinelOne:**
- EDR/XDR — agents, threats, sites, groups
- SDK/Client: `lib/services/sentinelone-client.ts` (direct client, no factory)
- Auth env var: `S1_API_KEY` or `SENTINELONE_API_KEY`
- Sync service: `lib/services/sentinelone-sync-service.ts`
- API: `/api/sentinelone/sync` (public POST, fire-and-forget)

**Duo Security:**
- 2FA/MFA monitoring — users, phones, auth logs, accounts
- SDK/Client: `lib/services/duo-client.ts` (direct client, no factory)
- Auth env vars: `DUO_IKEY`, `DUO_SKEY`, `DUO_HOST` — HMAC-SHA1 request signing
- Supports both Accounts API (parent) and Admin API (parent + child accounts)
- API: `/api/duo` (public POST; Duo-specific endpoints for sync, data retrieval)

**Zoom:**
- Videoconferencing — meeting analytics, users
- SDK/Client: `lib/services/zoom-factory.ts` → `getZoomClient()`, `isZoomConfigured()`, `lib/services/zoom-client.ts`
- Auth env vars: `ZOOM_ACCOUNT_ID`, `ZOOM_CLIENT_ID`, `ZOOM_CLIENT_SECRET` — Server-to-Server OAuth
- Sync service: `lib/services/zoom-sync-service.ts`
- API: `/api/zoom/sync` (public POST, fire-and-forget)

**QuickBooks Online:**
- Accounting — invoices, payments, deposits, purchases, journal entries
- SDK/Client: `lib/services/qbo-client.ts` (singleton, uses DATABASE_URL)
- Auth env vars: `QBO_CLIENT_ID`, `QBO_CLIENT_SECRET`, `QBO_REALM_ID`
- OAuth2 token management: tokens stored in `qbo_tokens` table (migration 014), auto-refreshed
- Sandbox mode: `QBO_SANDBOX=true` switches to sandbox URL
- Callback: `/api/qbo/auth` (public POST, OAuth redirect), `/api/qbo/disconnect` (public POST)
- Sync service: `lib/services/qbo-sync-service.ts`
- API: `/api/qbo/sync` (public POST, fire-and-forget)

**Zabbix:**
- Infrastructure monitoring — events, problems, hosts, metrics
- SDK/Client: `lib/services/zabbix-client.ts` (direct client, no factory)
- Auth env vars: `ZABBIX_API_URL`, `ZABBIX_API_TOKEN`
- Webhook handler: `/api/zabbix/webhook` (public POST)

**SalesBldr:**
- Sales engagement platform
- SDK/Client: `lib/services/salesbldr-client.ts` (direct client, no factory)
- Auth env vars: `SALESBLDR_API_URL`, `SALESBLDR_API_KEY`

**ipinfo.io:**
- IP geolocation (optional)
- Auth env var: `IPINFO_TOKEN` (optional, defaults to empty)

## Data Storage

**Databases:**
- PostgreSQL 16 — Primary data store
  - Connection: `POSTGRES_HOST`, `POSTGRES_PORT` (5432), `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` (or `DATABASE_URL`)
  - Client: `lib/services/postgres-client.ts` singleton via `postgresClient.query()`, `.transaction()`, `.upsert()`, `.bulkUpsert()`
  - Migrations: `migrations/*.sql` (numbered sequentially, applied in alphabetical order on Postgres init)
  - All columns: `snake_case`; API responses: `camelCase` (manual transformation)
  - Audit columns: `created_at`, `updated_at`, `synced_at`, `is_deleted`, `deleted_at`

**Cache:**
- Redis 7 (optional)
  - Connection: `REDIS_URL` (e.g., `redis://localhost:6380` in Docker)
  - Client: `lib/services/redis-client.ts` via `getRedisClient()`, `getCachedData()`, `setCachedData()`, `flushCache()`
  - TTL default: 300 seconds (5 minutes)
  - Graceful fallback: if REDIS_URL unset or connection fails, caching disabled

## Authentication & Identity

**Auth Provider:**
- Better Auth 1.4 — Magic link + TOTP 2FA + Microsoft OAuth
  - Implementation: `lib/auth.ts` configures plugins, session TTL, roles (user, admin, super-admin)
  - Database: Tables created in migration 012 (user, session, account, verification)
  - Default admin bootstrap: via `DEFAULT_ADMIN_EMAIL` env var, `lib/bootstrap.ts`
  - Session cookie handling: next-js plugin enabled
  - Account linking: Microsoft OAuth can link to existing accounts
  - Roles: `super-admin`, `admin`, `user`
  - RBAC: `lib/permissions.ts` defines `ac` (access-control) rules

**API Route Auth:**
- Helpers in `lib/auth-utils.ts`: `requireAuth()`, `requireAdmin()`, `requireSuperAdmin()`, `requirePermission(resource, action)`
- Middleware: `middleware.ts` checks session cookie existence; role verification happens in API routes
- Public routes: hardcoded in `middleware.ts` (webhooks, sync endpoints, health checks, auth callbacks, mobile, openclaw, kiosk, legal)

## Monitoring & Observability

**Error Tracking:**
- None (no Sentry/DataDog integration detected)

**Logs:**
- Console logging: `console.log()`, `console.error()`
- Slow query warnings: queries > 1000ms logged in `postgresClient.query()`

## AI & LLM

**Analyzer Pipeline:**
- Primary: Anthropic Claude API
  - SDK: `@anthropic-ai/sdk` 0.91.1
  - Auth: `ANTHROPIC_API_KEY` env var
  - Models: Haiku (stage 1, 6), Sonnet (stage 2, 5), Opus (stage 3, 4)
  - Worker: `lib/services/analyzer/worker.ts` (auto-starts in production, polled every 2s)
  - Pipeline: `lib/services/analyzer/pipeline.ts` (6 stages: triage, analysis, reasoning, fingerprint, aggregate, link-discovery)
  - Cost guard: `lib/services/analyzer/cost-guard.ts` (skips Opus above $2.00 estimated cost, flags for review)
  - Idempotency: per-request provider-scoped (`anthropic` | `openrouter`); same ticket can have both

**Alternate Provider:**
- OpenRouter (opt-in per request)
  - SDK: HTTP client, OpenAI-compatible format
  - Auth: `OPENROUTER_API_KEY` env var
  - Models: DeepSeek V4 Flash (fast), DeepSeek V4 Pro (standard), DeepSeek R1 (reasoning)
  - Call layer: `lib/services/llm/openrouter-call.ts`
  - Provider hints: `data_collection: 'deny'` (privacy floor), `sort: 'throughput'`, `allow_fallbacks: true`

**Model Constants:**
- `lib/services/llm/models.ts` — canonical model IDs and stage-model mappings
  - Anthropic: `claude-haiku-4-5`, `claude-sonnet-4-6`, `claude-opus-4-7`
  - OpenRouter: `deepseek/deepseek-v4-flash`, `deepseek/deepseek-v4-pro`, `deepseek/deepseek-r1-0528`

**Pricing & Token Tracking:**
- `lib/services/llm/pricing.ts` — per-token cost calculation
- `lib/services/analyzer/cost-guard.ts` — estimated cost ceiling enforcement

## File Storage

**Backblaze B2 (S3-compatible):**
- LogLift evidence upload/download
- Auth env vars: `B2_KEY_ID`, `B2_APP_KEY`
- Config env vars: `B2_BUCKET` (default: `wulf-audits`), `B2_REGION` (default: `us-west-002`), `B2_ENDPOINT` (default: `s3.us-west-002.backblazeb2.com`)
- SDK/Client: `lib/services/b2/client.ts` — presigned URLs (AWS SigV4), download/upload with object-key validation
- Max download: 25 MB
- Object key format validation: `{client_id_or_uuid}/{computer_name}/eventlogs_{timestamp}.json.gz` (path-traversal guard)

## CI/CD & Deployment

**Hosting:**
- Docker Compose (provided in `docker-compose.yml`)
- Traefik labels for reverse-proxy routing at `pulse.wulfconsulting.cloud`
- Standalone Next.js output for containerization

**CI Pipeline:**
- None detected; local testing only (vitest)
- Build: `npm run build` (turbopack)
- Type check: `npx tsc --noEmit --pretty`
- Lint: `npm run lint` (eslint)

## Webhooks & Callbacks

**Incoming Webhooks:**
- `/api/webhooks/autotask` — Autotask event notifications (public, HMAC-SHA1 verified)
- `/api/zabbix/webhook` — Zabbix problem notifications (public)
- `/api/rmm/loglift` — LogLift evidence uploads (public, verified via `x-openclaw-key` header)
- `/api/qbo/auth` — QuickBooks OAuth callback (public)
- `/api/qbo/disconnect` — QBO token revocation (public)

**Outgoing Webhooks:**
- Autotask write-back: workflow engine executes Autotask API calls (POST notes, status updates, custom fields)
- Workflow execution: `lib/services/workflow-engine.ts` chains actions after classification

**Fire-and-Forget Sync Endpoints:**
- `/api/datto-rmm/sync` (POST)
- `/api/veeam/sync` (POST)
- `/api/veeam/rpo-check` (POST)
- `/api/itglue/sync` (POST)
- `/api/sentinelone/sync` (POST)
- `/api/engagement/sync` (POST)
- `/api/zoom/sync` (POST)
- `/api/qbo/sync` (POST)
- All public, triggered by admin UI or cron schedule in sync-scheduler

## Environment Configuration

**Required env vars (production):**
- `BETTER_AUTH_URL` — must match deployed domain
- `BETTER_AUTH_SECRET` — session signing secret
- `DATABASE_URL` or `POSTGRES_*` — database connection
- `AUTOTASK_API_URL`, `AUTOTASK_USERNAME`, `AUTOTASK_SECRET`, `AUTOTASK_API_INTEGRATION_CODE` — Autotask API
- `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`, `MICROSOFT_TENANT_ID` — OAuth login
- `ANTHROPIC_API_KEY` — AI Analyzer (required if analyzer enabled)
- `DEFAULT_ADMIN_EMAIL` — initial super-admin account

**Optional env vars:**
- `REDIS_URL` — enables caching; graceful no-op if missing
- `MSGRAPH_*` — Microsoft Graph (engagement sync)
- `DATTO_RMM_*`, `VEEAM_VSPC_*`, `AUVIK_*`, `ADDIGY_*`, `ITGLUE_API_KEY`, `MIMECAST_*`, `S1_API_KEY`, `DUO_*`, `ZOOM_*`, `QBO_*`, `ZABBIX_*`, `SALESBLDR_*` — per-integration
- `OPENROUTER_API_KEY` — alternate LLM provider
- `B2_*` — LogLift evidence storage
- `IPINFO_TOKEN` — optional IP geolocation

**Secrets location:**
- `.env.local` (development, mounted read-only in Docker)
- Environment variables passed to container (production)
- *Note: `.env` file is committed to the repository; treat values as potentially real.*

**Integration disable mechanism:**
- Two sources (merged):
  1. `INTEGRATIONS_DISABLED` env var (legacy, comma/space-separated keys; aliases: `sentinelone` → `s1`, `datto` → `datto_rmm`, `it-glue` → `itglue`, `ms-graph` → `msgraph`)
  2. `integration_settings` table (migration 081) — admin-toggled at `/admin/integrations` without restart; cache invalidation immediate; audit columns: `disabled_by`, `disabled_at`, `disabled_reason`

---

*Integration audit: 2026-05-03*