| name | appfolio-debug-bundle |
| description | Collect AppFolio API debug evidence for support tickets.
Trigger: "appfolio debug".
|
| allowed-tools | Read, Write, Edit, Bash(npm:*), Bash(curl:*), Grep |
| version | 1.5.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","property-management","appfolio","real-estate"] |
| compatibility | Designed for Claude Code |
AppFolio Debug Bundle
Overview
This debug bundle collects diagnostic evidence from AppFolio property management API integrations
for support escalation and root cause analysis. It captures API connectivity against the
properties, tenants, and work orders endpoints, authentication status using client credential
pairs, recent error logs from integration pipelines, and SDK version information. The resulting
tarball gives support engineers everything they need to diagnose connectivity failures, auth
rejections, and data sync issues without requiring live access to your environment.
Prerequisites
curl, jq, tar installedAPPFOLIO_CLIENT_ID and APPFOLIO_CLIENT_SECRET configured (basic auth pair)APPFOLIO_BASE_URL set to your Stack API base (e.g., https://yourcompany.appfolio.com/api/v1)
Debug Collection Script
#!/bin/bash
set -euo pipefail
BUNDLE="debug-appfolio-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"
echo "=== Environment ===" > "$BUNDLE/environment.txt"
echo "Base URL: ${APPFOLIO_BASE_URL:-NOT SET}" >> "$BUNDLE/environment.txt"
echo "Client ID: ${APPFOLIO_CLIENT_ID:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Client Secret: ${APPFOLIO_CLIENT_SECRET:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo 'not installed')" >> "$BUNDLE/environment.txt"
echo "Timestamp: $(date -u)" >> "$BUNDLE/environment.txt"
echo "=== API Health ===" > "$BUNDLE/api-health.txt"
curl -sf -o "$BUNDLE/api-health.txt" -w "HTTP %{http_code} in %{time_total}s\n" \
-u "${APPFOLIO_CLIENT_ID}:${APPFOLIO_CLIENT_SECRET}" \
"${APPFOLIO_BASE_URL}/properties?per_page=1" 2>&1 || >
>
curl -sf -w \
-u \
>> 2>&1 || >>
>
curl -sf -w \
-u \
>> 2>&1 || >>
>
-100 /var/log/appfolio-sync/*. >> 2>/dev/null || >>
>
curl -sI -u \
2>/dev/null | grep -i >> || >>
>
npm 2>/dev/null | grep -i appfolio >> || >>
tar -czf && -rf
Analyzing the Bundle
tar -xzf debug-appfolio-*.tar.gz
cat debug-appfolio-*/environment.txt
cat debug-appfolio-*/api-health.txt
cat debug-appfolio-*/rate-limits.txt
jq '.errors' debug-appfolio-*/work-orders.txt 2>/dev/null
Common Issues
| Symptom | Check in Bundle | Fix |
|---|
| 401 on all endpoints | environment.txt shows client ID/secret NOT SET | Set APPFOLIO_CLIENT_ID and APPFOLIO_CLIENT_SECRET in env |
| 403 Forbidden on tenants | tenants.txt HTTP 403 | Stack API scope missing; request tenant read permission in AppFolio partner portal |
| 429 Too Many Requests | rate-limits.txt shows retry-after header | Back off and implement exponential retry; AppFolio allows 120 req/min |
| Timeout on work orders | api-health.txt shows time > 30s | Reduce per_page parameter; filter by updated_since to narrow result set |
| Empty property list | api-health.txt returns [] | Verify APPFOLIO_BASE_URL points to correct portfolio; check property group filters |
| SSL certificate error | api-health.txt shows curl SSL error | Update CA bundle: sudo update-ca-certificates; check proxy settings |
Automated Health Check
async function checkAppFolioHealth(): Promise<{
status: string;
latencyMs: number;
endpoints: Record<string, number>;
}> {
const baseUrl = process.env.APPFOLIO_BASE_URL;
const creds = Buffer.from(
`${process.env.APPFOLIO_CLIENT_ID}:${process.env.APPFOLIO_CLIENT_SECRET}`
).toString("base64");
const headers = { Authorization: `Basic ${creds}` };
const endpoints = ["properties", "tenants", "work_orders"];
const results: Record<string, number> = {};
const start = Date.now();
for (const ep of endpoints) {
const res = await fetch(`${baseUrl}/${ep}?per_page=1`, { headers });
results[ep] = res.status;
}
return {
status: .(results).( s === ) ? : ,
: .() - start,
: results,
};
}
Resources
Next Steps
See appfolio-rate-limits.
