jeremylongshore/tons-of-skills-marketplace

AppFolio Local Dev Loop

Overview

Local development workflow for AppFolio property management API integration. Provides a fast feedback loop with mock property, tenant, and lease endpoints so you can build and test integrations without consuming live API quota. Toggle between mock mode for rapid iteration and sandbox mode for pre-deployment validation against the real AppFolio Stack API.

Prerequisites

• A mock-only local environment with synthetic property, tenant, lease, and work-order fixtures that contain no production addresses, names, or payments.
• A separately managed sandbox credential and an approved safe-read fixture for the dedicated integration lane; it is never loaded by the local dev server.
• A log policy that records request shape and status only, plus an explicit owner for sandbox quota, fixture reset, and credential rotation.

Instructions

1. Run the local server only in mock mode and exercise reads/writes against synthetic routes with deterministic fixtures.
2. Test request validation, idempotency, redaction, and error handling in unit tests before any sandbox connectivity check.
3. Run the sandbox lane separately with the contract-bound managed client and one authorized safe-read fixture; do not turn a local proxy into a live API tunnel.
4. Stop when the fixture, credentials, request budget, or output redaction is unverified, then correct the environment before continuing.

Environment Setup

cp .env.example .env
# Leave provider credentials blank locally. Mock mode is the default.
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express

Dev Server

// src/dev/server.ts
import express from "express";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) throw new Error("Local server is mock-only; use the managed sandbox integration lane");
const { mountMockRoutes } = require("./mocks");
mountMockRoutes(app);
app.listen(3001, () => console.log(`AppFolio dev server on :3001 [mock=${MOCK}]`));

Mock Mode

// src/dev/mocks.ts — realistic property management responses
export function mountMockRoutes(app: any) {
  app.get("/api/v1/properties", (_req: any, res: any) => res.json([
    { id: "prop_1", name: "Sunset Apartments", address: { street: "123 Sunset Blvd", city: "Los Angeles", state: "CA" }, property_type: "residential", unit_count: 24 },
    { id: "prop_2", name: "Downtown Office", address: { street: "456 Main St", city: "San Francisco", state: "CA" }, property_type: "commercial", unit_count: 8 },
  ]));
  app.get("/api/v1/tenants", (_req: any, res: any) => res.json([
    { id: "t1", first_name: "Jane", last_name: "Smith", email: "[email protected]", unit_id: "u1", lease_id: "l1" },
  ]));
  app.get("/api/v1/leases", (_req: any, res: any) => res.json([
    { id: "l1", unit_id: "u1", start_date: "2025-01-01", end_date: "2026-01-01", rent_amount: 2500, status: "active" },
  ]));
  app.post("/api/v1/work-orders", (req: any, res: any) => res.status(201).json({ id: "wo_1", ...req.body, status: "open" }));
}

Testing Workflow

npm run dev:mock &                    # Start mock server in background
npm run test                          # Unit tests with vitest
npm run test -- --watch               # Watch mode for rapid iteration
npm run test:sandbox                     # Managed, read-only sandbox lane

Debug Tips

• Set DEBUG=express:* to trace all route matching and middleware execution
• Use local test assertions for fixture counts and schema shape, not raw tenant payload dumps
• Check X-RateLimit-Remaining header when testing against the live API
• AppFolio sandbox returns 403 for properties you do not own — verify your API key scope
• Use interceptors only for redacted endpoint/status/count telemetry during development

Output

• A deterministic mock-only local server with synthetic property-management fixtures and no provider credential dependency
• Unit-test evidence for validation, idempotency, and PII-safe observability
• A separate managed sandbox result containing only redacted safe-read status

Examples

For a work-order UI change, add a synthetic mock fixture and test the request schema plus duplicate-submission behavior locally. Assert the returned ID and status without emitting the request body or tenant record. After unit tests pass, run the dedicated sandbox lane against one approved safe-read fixture. If mock mode is disabled, a sandbox credential appears locally, or a response contains unredacted tenant fields, stop the run and restore the local boundary.

Error Handling

Issue	Cause	Fix
401 Unauthorized	Invalid or expired API key	Regenerate at AppFolio Stack portal
403 Forbidden	Key lacks scope for endpoint	Request additional permissions
404 Not Found	Wrong property ID or path	Verify resource exists in sandbox
429 Too Many Requests	Rate limit exceeded	Add exponential backoff, use mock mode
ECONNREFUSED :3001	Dev server not running	Run npm run dev:mock first

Resources

• AppFolio Stack APIs
• AppFolio Engineering Blog

Next Steps

See appfolio-debug-bundle.