---
phase: 13-scheduler-admin-toggle
plan: 02
subsystem: api
tags: [integration-health, admin-toggle, pax8, postgres]

# Dependency graph
requires:
  - phase: 10-pax8-client-auth-foundation
    provides: pax8-factory.ts (isPax8Configured, PAX8_CLIENT_ID/PAX8_CLIENT_SECRET env vars)
  - phase: 11-company-catalog-subscription-sync
    provides: app/api/pax8/sync/route.ts (POST/GET handlers, Pax8SyncService)
provides:
  - PAX8 as a toggleable row on /admin/integrations (checkConfigOnly call site)
  - 403 disabled-gate on POST /api/pax8/sync closing the manual "side door"
affects: [13-03 (scheduler branch + live verification wave)]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "DB-backed disabled toggle enforced inline at the top of a route handler (first precedent in this codebase for gating an action, not just display)"

key-files:
  created: []
  modified:
    - lib/services/integration-health.ts
    - app/api/pax8/sync/route.ts

key-decisions:
  - "Used category 'finance' for the PAX8 health-check row (matches qbo) since IntegrationHealth['category'] has no vendor/marketplace option, per plan instruction"
  - "Disabled-check inlined in POST rather than extracted into a shared helper with the scheduler check (per plan D-01, deferred to 13-03)"

patterns-established:
  - "Pattern: gate a manual-trigger route on integration_settings.disabled via a first-statement inline query, mirroring the existing getDbDisabledKeys() query shape but scoped to a single key"

requirements-completed: [PAX8-09]

# Metrics
duration: 6min
completed: 2026-07-11
---

# Phase 13 Plan 02: Scheduler & Admin Toggle (admin surface) Summary

**PAX8 registered as a toggleable /admin/integrations row and POST /api/pax8/sync now returns 403 while PAX8 is disabled via the operator toggle.**

## Performance

- **Duration:** 6 min
- **Started:** 2026-07-11T13:XX:XXZ
- **Completed:** 2026-07-11T13:XX:XXZ
- **Tasks:** 2 completed
- **Files modified:** 2

## Accomplishments
- PAX8 now appears as a row (key `pax8`, name `PAX8`, category `finance`) in `checkIntegrationHealth()` output, making it toggleable on `/admin/integrations` and flowing through the existing `applyDisableOverlay` with zero changes to that overlay logic.
- `POST /api/pax8/sync` now returns HTTP 403 as its very first action when `integration_settings.key='pax8'` has `disabled=true`, closing the manual-trigger "side door" per D-02 — no other behavior changed.

## Task Commits

Each task was committed atomically:

1. **Task 1: Register PAX8 as an integration-health row** - `3c114ae` (feat)
2. **Task 2: Gate POST /api/pax8/sync on the disabled toggle (403)** - `fdc9919` (feat)

_Note: No TDD tasks in this plan; single commit per task._

## Files Created/Modified
- `lib/services/integration-health.ts` - Added `Promise.resolve(checkConfigOnly('pax8', 'PAX8', 'finance', ['PAX8_CLIENT_ID', 'PAX8_CLIENT_SECRET']))` to the `Promise.all` array inside `checkIntegrationHealth()`, immediately after the `appgate` entry.
- `app/api/pax8/sync/route.ts` - Inserted a disabled-check as the first statement of `POST`: queries `SELECT disabled FROM integration_settings WHERE key = 'pax8'` and returns 403 with `{ error: 'PAX8 is disabled', message: '...' }` when `rows[0]?.disabled === true`. `GET` unchanged, no new imports (`postgresClient` already imported at the top of the file).

## Decisions Made
- Category `'finance'` chosen for the PAX8 health row (matches `qbo`'s billing/subscription-data classification) since the `IntegrationHealth['category']` union has no vendor/marketplace member — per plan instruction, the union was not extended.
- The disabled-check in the route is a standalone inline query, not a shared helper with the forthcoming scheduler branch (13-03) — per plan D-01, this separation is intentional for this phase.

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## Threat Flags

None — both edits are covered by the plan's own `<threat_model>` (T-13-01 mitigated by the 403 gate, T-13-04 mitigated by the constant-literal query, T-13-05 accepted for the error message). No new undocumented surface introduced.

## Known Stubs

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- Both `checkConfigOnly('pax8', ...)` in `integration-health.ts` and the 403 gate in `app/api/pax8/sync/route.ts` are ready for 13-03's live verification (row appears on `/admin/integrations`, 403 confirmed when toggled off) and the scheduler branch (`pax8-daily` in `sync-scheduler.ts`) which reuses the same `SELECT disabled FROM integration_settings WHERE key = 'pax8'` query shape.
- No blockers.

## Self-Check: PASSED

All claimed files exist (`lib/services/integration-health.ts`, `app/api/pax8/sync/route.ts`, this SUMMARY.md) and all claimed commits (`3c114ae`, `fdc9919`, `6413f99`) are present in git history.

---
*Phase: 13-scheduler-admin-toggle*
*Completed: 2026-07-11*
