Que fait Modèles SDK AppFolio ?
Aperçu
Modèles prêts pour la production pour l'API REST AppFolio de gestion immobilière. AppFolio utilise l'authentification de base HTTP avec des identifiants client et renvoie des réponses JSON pour les propriétés, les locataires, les baux et les ordres de travail. Un client singleton structuré empêche la prolifération des informations d'identification, applique une gestion cohérente des erreurs et centralise la logique de pagination sur tous les points de terminaison de gestion immobilière.
Prérequis
- Une URL de base vérifiée par le fournisseur, une méthode d'authentification, une portée de point de terminaison et un chemin d'injection de secret géré pour le portefeuille cible.
- Validation de schéma, délais d'attente de requête, limites de débit spécifiques aux points de terminaison et clés d'idempotence pour toutes les méthodes de service capables de mutation.
- Éléments synthétiques pour les tests unitaires ; les charges utiles de production des locataires, des baux et des paiements ne doivent pas devenir le contenu par défaut des mocks, des journaux ou des messages d'erreur.
Instructions
- Construisez un client lié par contrat par environnement d'exécution et rejetez les configurations manquantes ou invalides avant le début des requêtes.
- Validez les limites de requête et les formes de réponse à la frontière du service, puis transmettez uniquement les champs typés minimisés aux appelants.
- Renvoyez un
429classifié ou un échec d'écriture inconnu à l'appelant ; ne réessayez que les opérations idempotentes après que l'appelant a enregistré le curseur/clé et le délai. - Gardez les flux d'écriture derrière des contrôles d'autorisation, d'audit et de rapprochement explicites plutôt que de les intégrer dans des assistants de commodité SDK génériques.
Client Singleton
import axios, { AxiosInstance } from 'axios';
let _client: AxiosInstance | null = null;
export function getClient(): AxiosInstance {
if (!_client) {
const clientId = process.env.APPFOLIO_CLIENT_ID;
const clientSecret = process.env.APPFOLIO_CLIENT_SECRET;
const baseURL = process.env.APPFOLIO_BASE_URL;
if (!clientId || !clientSecret || !baseURL) throw new Error('APPFOLIO_CLIENT_ID, SECRET, and BASE_URL required');
_client = axios.create({ baseURL, auth: { username: clientId, password: clientSecret }, timeout: 30000 });
}
return _client;
}
Gestionnaire d'Erreurs
export class AppFolioError extends Error {
constructor(public status: number, public code: string, message: string) { super(message); }
}
export async function safeCall<T>(operation: string, fn: () => Promise<T>): Promise<T> {
try { return await fn(); }
catch (err: any) {
const status = err.response?.status ?? 0;
if (status === 429) {
const retryAfter = err.response?.headers?.['retry-after'];
throw new AppFolioError(429, 'RATE_LIMIT', `Retry after ${retryAfter ?? 'provider-directed delay'}; do not replay an unknown write automatically`);
}
if (status === 401) throw new AppFolioError(401, 'AUTH', 'Invalid APPFOLIO_CLIENT_ID or SECRET');
throw new AppFolioError(status, 'API_ERROR', `${operation} failed [${status}]: ${err.message}`);
}
}
Constructeur de Requêtes
class AppFolioQuery {
private params: Record<string, string> = {};
status(s: 'active' | 'past' | 'future') { this.params.status = s; return this; }
propertyId(id: string) { this.params.property_id = id; return this; }
page(n: number) { this.params.page = String(n); return this; }
perPage(n: number) { this.params.per_page = String(Math.min(n, 200)); return this; }
since(date: string) { this.params.updated_since = date; return this; }
build() { return this.params; }
}
// Utilisation : new AppFolioQuery().status('active').perPage(50).build();
Types de Réponse
interface Property {
id: string; name: string; property_type: 'residential' | 'commercial' | 'mixed';
address: { street: string; city: string; state: string; zip: string };
unit_count: number; status: string;
}
interface Tenant {
id: string; first_name: string; last_name: string;
email: string; phone: string; unit_id: string; lease_id: string;
}
interface Lease {
id: string; unit_id: string; tenant_id: string;
start_date: string; end_date: string; rent_amount: number; status: 'active' | 'expired' | 'future';
}
interface WorkOrder {
id: string; property_id: string; unit_id: string;
description: string; priority: 'low' | 'medium' | 'high' | 'emergency';
status: 'open' | 'in_progress' | 'completed';
}
Utilitaires de Test
export function mockProperty(overrides: Partial<Property> = {}): Property {
return { id: 'prop-001', name: 'Maple Ridge Apts', property_type: 'residential',
address: { street: '100 Main St', city: 'Austin', state: 'TX', zip: '78701' },
unit_count: 24, status: 'active', ...overrides };
}
export function mockLease(overrides: Partial<Lease> = {}): Lease {
return { id: 'lease-001', unit_id: 'unit-001', tenant_id: 'ten-001',
start_date: '2025-01-01', end_date: '2026-01-01', rent_amount: 1500, status: 'active', ...overrides };
}
Gestion des Erreurs
| Modèle | Quand l'utiliser | Exemple |
|---|---|---|
Gestionnaire safeCall | Tous les appels API | Empêche les 4xx/5xx non capturés de faire planter les flux |
| Nouvelle tentative initiée par l'appelant sur 429 | Lectures par lots idempotentes limitées en débit | Préserver le curseur/clé, respecter Retry-After, puis réessayer délibérément |
| Validation de l'authentification | Initialisation du client | Lève une exception tôt si les informations d'identification sont manquantes |
| Boucle de pagination | Liste des propriétés/locataires | Incrémenter page jusqu'à réponse vide |
Résultat
- Un client API validé et lié par contrat avec un délai d'attente centralisé et un comportement de classification des erreurs
- Paramètres de requête limités et réponses typées minimisées pour les appelants de service
- Résultats explicites de limite de débit et d'écriture inconnue nécessitant des décisions de curseur/idempotence/rapprochement initiées par l'appelant
Exemples
Pour une lecture de liste de propriétés, construisez une requête avec une taille de page plafonnée, exécutez-la via safeCall, et vérifiez les identifiants de propriété retournés et le nombre par rapport à un élément synthétique. Pour une mutation, persistez une clé d'idempotence avant l'envoi et traitez un délai d'attente ou un 429 comme une condition de pause/rapprochement plutôt que d'appeler à nouveau la fonction. Si la configuration du client, le schéma de réponse ou le résultat de l'écriture n'est pas vérifié, arrêtez le flux de travail et signalez une erreur expurgée au propriétaire.
Ressources
Prochaines Étapes
Appliquez les modèles dans appfolio-core-workflow-a.