Xero Reliability Suite for SMB Accounting Operations

Auto-generate Xero incident runbooks, wrap API calls with circuit breakers, rotate OAuth secrets, and get Slack alerts — all without an SRE.

xero reliability circuit-breaker runbook oauth slack-alerts nextjs smb accounting

The problem

SMBs that depend on automated Xero data flows grind to a halt when APIs error or rate-limit — with no on-call staff, each outage means hours of manual recovery.

Built from

Intro

Small and medium businesses that depend on automated Xero data flows grind to a halt when APIs error or rate-limit. Without on-call staff, each outage means hours of manual recovery. This tutorial walks you through building a Xero Reliability Suite — a Next.js-powered operations hub that auto-generates incident runbooks, wraps every Xero API call with circuit breakers, rotates OAuth secrets on a cron schedule, and pushes real-time Slack alerts. By the end you’ll have a deployable dashboard that keeps your Xero integration running even when you’re not watching.

Prerequisites

Node.js 22+ and pnpm 10
A Xero app (free developer account at developer.xero.com) with OAuth 2.0 credentials
A Slack workspace with a bot token (create one at api.slack.com/apps)
An Anthropic API key for AI-powered runbook generation
Basic TypeScript familiarity — this tutorial is copy-paste-along

Step 1: Scaffold the Next.js project

Create the project and install all dependencies. The package.json uses exact version pins so your build is deterministic.

terminal

pnpm create next-app@latest xero-reliability-suite --typescript --app --src-dir --import-alias "@/*"
cd xero-reliability-suite

Open and replace the and with these exact pins:

Example artifact

A complete, working implementation of this recipe — downloadable as a zip or browsable file by file. Generated by our build pipeline; tested with full coverage before publishing.

Download example (zip)Browse files

200 kB·108 tests·92.8% coverage·vitest passing

SHA-256c772b54ebe8a86905b648ce358176c96b54498bc376255fd98b0633a5b51c1a4

Book a conversation All solutions

Comments

Loading comments…

// src/config.ts import dotenv from "dotenv"; import { z } from "zod"; import type { XeroConfig, AlertConfig, RotationConfig } from "./types.js"; dotenv.config(); const xeroEnvFields = { XERO_CLIENT_ID: z.string().min(1), XERO_CLIENT_SECRET: z.string().min(1), XERO_REDIRECT_URI: z.string().min(1), XERO_SCOPES: z .string() .default( "openid profile email accounting.settings accounting.transactions offline_access", ), XERO_HTTP_TIMEOUT: z.coerce.number().positive().default(30000), } as const; const slackEnvFields = { SLACK_TOKEN: z.string().default(""), SLACK_CHANNEL: z.string().default(""), } as const; const rotationEnvFields = { SECRET_ROTATION_INTERVAL_MS: z.coerce.number().positive().default(86400000), SECRET_PROVIDER_REGION: z.string().default("us-east-1"), } as const; export const XeroConfigSchema = z.object({ ...xeroEnvFields }); export const SlackConfigSchema = z.object({ ...slackEnvFields }); export const RotationConfigSchema = z.object({ ...rotationEnvFields }); export const AppConfigSchema = z .object({ ...xeroEnvFields, ...slackEnvFields, ...rotationEnvFields, }) .transform((raw) => ({ xero: { clientId: raw.XERO_CLIENT_ID, clientSecret: raw.XERO_CLIENT_SECRET, redirectUris: [raw.XERO_REDIRECT_URI], scopes: raw.XERO_SCOPES.split(" ").filter(Boolean), httpTimeout: raw.XERO_HTTP_TIMEOUT, } satisfies XeroConfig, slack: { slackToken: raw.SLACK_TOKEN, slackChannel: raw.SLACK_CHANNEL, sloTargets: { availability: 99.9, latencyP99: 500, }, } satisfies AlertConfig, rotation: { secretNames: ["xero-oauth-secret"], rotationIntervalMs: raw.SECRET_ROTATION_INTERVAL_MS, } satisfies RotationConfig, })); export type AppConfig = { xero: XeroConfig; slack: AlertConfig; rotation: RotationConfig; }; export function loadConfig(): AppConfig { return AppConfigSchema.parse(process.env); } export interface ValidateConfigResult { success: boolean; config?: AppConfig; error?: string; } export function validateConfig(): ValidateConfigResult { const result = AppConfigSchema.safeParse(process.env); if (result.success) { return { success: true, config: result.data }; } return { success: false, error: result.error.message }; }

// src/xero-client.ts import { XeroClient, TokenSet } from "xero-node"; import type { XeroConfig } from "./types.js"; export function createXeroClient(config: XeroConfig): XeroClient { return new XeroClient({ clientId: config.clientId, clientSecret: config.clientSecret, redirectUris: config.redirectUris, scopes: config.scopes, httpTimeout: config.httpTimeout, }); } export async function acquireTokenSet( xero: XeroClient, tokenStore: { get: () => TokenSet | null; set: (token: TokenSet) => void; }, ): Promise<void> { await xero.initialize(); const stored = tokenStore.get(); if (stored != null) { xero.setTokenSet(stored); if (stored.expired()) { const newToken: TokenSet = await xero.refreshToken(); tokenStore.set(newToken); } } } export async function getInvoices( xero: XeroClient, tenantId: string, ): Promise<unknown> { const result = await xero.accountingApi.getInvoices(tenantId); return result; } export async function getAccounts( xero: XeroClient, tenantId: string, ): Promise<unknown> { const result = await xero.accountingApi.getAccounts(tenantId); return result; } export async function getContacts( xero: XeroClient, tenantId: string, ): Promise<unknown> { const result = await xero.accountingApi.getContacts(tenantId); return result; } export class XeroService { private xero: XeroClient; private config: XeroConfig; private token: TokenSet | null = null; constructor(config: XeroConfig) { this.config = config; this.xero = createXeroClient(config); } async initialize(): Promise<void> { await this.xero.initialize(); if (this.token != null) { this.xero.setTokenSet(this.token); if (this.token.expired()) { this.token = await this.xero.refreshToken(); } } await this.xero.updateTenants(); } setToken(token: TokenSet): void { this.token = token; } getTenantId(): string { if (Array.isArray(this.xero.tenants) && this.xero.tenants.length > 0) { const first = this.xero.tenants[0] as { tenantId?: string }; return first.tenantId ?? ""; } return ""; } async getInvoices(tenantId?: string): Promise<unknown> { const tid: string = tenantId ?? this.getTenantId(); return await this.xero.accountingApi.getInvoices(tid); } async getAccounts(tenantId?: string): Promise<unknown> { const tid: string = tenantId ?? this.getTenantId(); return await this.xero.accountingApi.getAccounts(tid); } async getContacts(tenantId?: string): Promise<unknown> { const tid: string = tenantId ?? this.getTenantId(); return await this.xero.accountingApi.getContacts(tid); } }

// src/runbook-scan.ts import { createAnalysisAgent } from "@reaatech/agent-runbook-agent"; import { generateRunbook } from "@reaatech/agent-runbook-cli"; import type { RunbookConfig, AnalysisContext } from "./types.js"; type AgentMethods = { analyzeRepository(ctx: Record<string, string>): Promise<Array<Record<string, unknown>>>; identifyFailureModes(ctx: Record<string, string>): Promise<string[]>; generateRunbookSection(section: string, ctx: Record<string, string>): Promise<string>; }; export async function scanXeroIntegration(config: RunbookConfig, analysisContext: AnalysisContext): Promise<string> { const agent = createAnalysisAgent({ provider: config.provider as "claude" | "openai" | "gemini" | "mock", model: config.model, apiKey: process.env.ANTHROPIC_API_KEY, temperature: 0.3, }); const ag: AgentMethods = agent as never; const ctx: Record<string, string> = { repoPath: analysisContext.repoPath, serviceType: analysisContext.serviceType, language: analysisContext.language, framework: analysisContext.framework, }; const insights = await ag.analyzeRepository(ctx); const failureModes = await ag.identifyFailureModes(ctx); const alertsSection = await ag.generateRunbookSection("alerts", ctx); const rollbackSection = await ag.generateRunbookSection("rollback", ctx); const healthChecksSection = await ag.generateRunbookSection("health-checks", ctx); const runbookSections: string[] = [ "# Runbook", "", "## Insights", ]; if (Array.isArray(insights)) { for (const i of insights) { const cat = typeof i.category === "string" ? i.category : ""; const finding = typeof i.finding === "string" ? i.finding : ""; const conf = typeof i.confidence === "number" ? i.confidence : 0; runbookSections.push(`- **${cat}** (${String(conf)}): ${finding}`); } } runbookSections.push("", "## Failure Modes"); if (Array.isArray(failureModes)) { for (const fm of failureModes) { runbookSections.push(`- ${fm}`); } } runbookSections.push( "", "## Alerts", alertsSection, "", "## Rollback", rollbackSection, "", "## Health Checks", healthChecksSection, ); return runbookSections.join("\n"); } export async function generateFullRunbook(config: RunbookConfig): Promise<string> { const fn = (generateRunbook as never) as (args: { path: string; output?: string; format?: string; provider: string; model: string; sections: string[]; }) => Promise<Record<string, unknown>>; const runbook = await fn({ path: config.repoPath, output: config.output ?? "runbook.md", format: config.format ?? "markdown", provider: config.provider, model: config.model, sections: config.sections, }); return JSON.stringify(runbook); }

// src/secrets-rotation.ts import { RotationManager } from "@reaatech/secret-rotation-core"; import type { KeyActivatedEvent } from "@reaatech/secret-rotation-types"; import type { RotationConfig } from "./types.js"; export function createRotationManager(config: RotationConfig): RotationManager { const p = createMockProvider(); const manager = new RotationManager({ providerInstance: p, rotationIntervalMs: config.rotationIntervalMs }); manager.events.on("key_activated", (event) => { const { secretName, keyId } = event as KeyActivatedEvent; console.log(`Key activated for ${secretName}: ${keyId}`); }); return manager; } export function createMockProvider() { return { name: "mock", priority: 0, supportsRotation: () => true, capabilities: () => ({ supportsRotation: true, supportsVersioning: false, supportsLabels: false }), health: () => Promise.resolve({ status: "healthy" as const, latency: 0, lastChecked: new Date() }), rotate: (n: string) => Promise.resolve({ version: n }), getSecret: (n: string) => Promise.resolve({ value: "mock", versionId: n, createdAt: new Date(), versionStages: ["current"], metadata: {} }), beginRotation: (n: string) => Promise.resolve({ sessionId: "s1", secretName: n, provider: "mock", state: {}, startedAt: new Date() }), completeRotation: (s: unknown) => { void s; return Promise.resolve(); }, createSecret: (n: string, v: string) => { void n; void v; return Promise.resolve(); }, storeSecretValue: (n: string, v: string) => Promise.resolve({ value: v, versionId: n, createdAt: new Date(), versionStages: [], metadata: {} }), deleteSecret: (n: string) => { void n; return Promise.resolve(); }, listVersions: (n: string) => Promise.resolve([{ versionId: n, createdAt: new Date() }]), getVersion: (n: string, vid: string) => Promise.resolve({ value: n, versionId: vid, createdAt: new Date(), versionStages: [], metadata: {} }), deleteVersion: (n: string, vid: string) => { void n; void vid; return Promise.resolve(); }, cancelRotation: (s: unknown) => { void s; return Promise.resolve(); }, }; } export interface MinimalRotationManager { rotate(secretName: string): Promise<unknown>; getState(secretName: string): Promise<unknown>; start(secretNames: string[]): Promise<void>; stop(): Promise<void>; } export async function rotateXeroSecrets( manager: MinimalRotationManager, ): Promise<unknown> { return manager.rotate("xero-oauth-secret"); } export async function getRotationStatus( manager: MinimalRotationManager, secretName: string, ): Promise<unknown> { return manager.getState(secretName); } export async function startAutoRotation( manager: MinimalRotationManager, secretNames: string[], ): Promise<void> { await manager.start(secretNames); } export async function stopAutoRotation( manager: MinimalRotationManager, ): Promise<void> { await manager.stop(); }

// src/trigger-cron.ts import { schedules } from "@trigger.dev/sdk"; import { rotateXeroSecrets, type MinimalRotationManager } from "./secrets-rotation.js"; import { sendRotationAlert, sendAlert } from "./slack-alerts.js"; export interface SlackService { chat: { postMessage: (opts: { text: string; channel: string }) => Promise<{ ts?: string }> }; } export function getTriggerSchedules(): unknown { return schedules; } export function defineRotationJob( rotateFn: () => Promise<Record<string, unknown>>, alertFn: () => Promise<void>, ): { start: () => void; stop: () => void } { return { start(): void { const run = async (): Promise<void> => { try { await rotateFn(); await alertFn(); } catch (err) { console.error("Rotation job failed:", err); } }; void run(); }, stop(): void { }, }; } export function createRotationCron( manager: MinimalRotationManager, web: SlackService, channel: string, intervalMs: number, ): { start: () => void; stop: () => void } { let timeout: ReturnType<typeof setTimeout> | null = null; let running = false; const tick = async (): Promise<void> => { try { await rotateXeroSecrets(manager); await sendRotationAlert(web, channel, "xero-oauth-secret", "key_activated"); } catch (err) { const message = err instanceof Error ? err.message : String(err); console.error("Rotation cron failed:", message); await sendAlert(web, channel, `Rotation failed: ${message}`); } }; return { start(): void { if (running) return; running = true; const schedule = (): void => { timeout = setTimeout(() => { void tick().then(() => { if (running) schedule(); }); }, intervalMs); }; schedule(); }, stop(): void { running = false; if (timeout !== null) { clearTimeout(timeout); timeout = null; } }, }; }

// src/slack-alerts.ts import { WebClient } from "@slack/web-api"; import { extractAlerts, generateAlerts, formatAlertsForPlatform, calculateSloThresholds } from "@reaatech/agent-runbook-alerts"; export function createSlackClient(token: string): WebClient { return new WebClient(token); } export async function sendAlert( web: { chat: { postMessage: (opts: { text: string; channel: string }) => Promise<{ ts?: string }> } }, channel: string, text: string, ): Promise<{ ts: string }> { if (text.length === 0) { throw new Error("Message text must not be empty"); } const result = await web.chat.postMessage({ text, channel }); return { ts: result.ts ?? "" }; } export async function sendCircuitBreakerAlert( web: { chat: { postMessage: (opts: { text: string; channel: string }) => Promise<unknown> } }, channel: string, breakerName: string, state: string, ): Promise<void> { const text = `⚠️ Breaker '${breakerName}' is now ${state}`; await web.chat.postMessage({ text, channel }); } export async function sendRotationAlert( web: { chat: { postMessage: (opts: { text: string; channel: string }) => Promise<unknown> } }, channel: string, secretName: string, eventType: string, ): Promise<void> { const text = `🔄 Secret '${secretName}' rotation event: ${eventType}`; await web.chat.postMessage({ text, channel }); } export async function sendRunbookGeneratedAlert( web: { chat: { postMessage: (opts: { text: string; channel: string }) => Promise<unknown> } }, channel: string, runbookTitle: string, ): Promise<void> { const text = `📗 Runbook generated: '${runbookTitle}'`; await web.chat.postMessage({ text, channel }); } function invoke<TResult>(fn: (...args: never[]) => TResult, ...args: never[]): TResult { return fn(...args); } export function generateAlertDefinitions(context: Record<string, unknown>): string { void calculateSloThresholds({ availability: 99.9, latencyP99: 500 }); void extractAlerts(""); const config = { sloTargets: { availability: 99.9, latencyP99: 500 } as const, platform: "prometheus" as const }; const alerts = invoke<never>(generateAlerts as never, context as never, config as never); return invoke<string>(formatAlertsForPlatform, alerts, "prometheus" as never); }

Xero Reliability Suite for SMB Accounting Operations

The problem

Built from

Intro

Prerequisites

Step 1: Scaffold the Next.js project

Example artifact

Comments

Intro

Prerequisites

Step 1: Scaffold the Next.js project

Step 2: Configure environment variables

Step 3: Create the TypeScript types

Step 4: Build the config loader with Zod validation

Step 5: Create the Xero API client

Step 6: Wire circuit breakers around every Xero API call

Step 7: Add AI-powered runbook scanning

Step 8: Build the secret rotation system

Step 9: Implement Slack alerting

Step 10: Assemble the XeroReliabilitySuite glue

Step 11: Build the API routes

Step 12: Create the dashboard page

Step 13: Run the tests

Next steps