Padrões do SDK AppFolio
Visão Geral
Padrões prontos para produção para a API REST de gerenciamento de propriedades do AppFolio. O AppFolio usa autenticação HTTP Basic com credenciais de cliente e retorna respostas JSON para propriedades, inquilinos, contratos de locação e ordens de serviço. Um cliente singleton estruturado previne a proliferação de credenciais, impõe tratamento de erros consistente e centraliza a lógica de paginação em todos os endpoints de gerenciamento de propriedades.
Pré-requisitos
- Uma URL base verificada pelo provedor, método de autenticação, escopo do endpoint e caminho de injeção de segredo gerenciado para o portfólio alvo.
- Validação de esquema, timeouts de requisição, limites de taxa específicos do endpoint e chaves de idempotência para todos os métodos de serviço com capacidade de mutação.
- Fixtures sintéticas para testes unitários; payloads de produção de inquilinos, contratos de locação e pagamentos não devem se tornar conteúdo padrão de mocks, logs ou mensagens de erro.
Instruções
- Construa um cliente vinculado a um contrato por tempo de execução e rejeite configurações ausentes ou inválidas antes do início das requisições.
- Valide limites de consulta e formatos de resposta na fronteira do serviço, depois passe apenas campos tipados minimizados para os chamadores.
- Retorne um erro
429classificado ou uma falha de escrita desconhecida para o chamador; tente novamente apenas operações idempotentes após o chamador registrar o cursor/chave e atraso. - Mantenha fluxos de escrita atrás de controles explícitos de autorização, auditoria e reconciliação, em vez de incorporá-los em auxiliares genéricos de conveniência do SDK.
Cliente 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;
}
Wrapper de Erro
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}`);
}
}
Construtor de Consultas
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; }
}
// Uso: new AppFolioQuery().status('active').perPage(50).build();
Tipos de Resposta
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';
}
Utilitários de Teste
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 };
}
Tratamento de Erros
| Padrão | Quando Usar | Exemplo |
|---|---|---|
Wrapper safeCall | Todas as chamadas de API | Impede que erros 4xx/5xx não capturados interrompam fluxos |
| Retentativa de propriedade do chamador em 429 | Leituras em lote idempotentes com limite de taxa | Preserve cursor/chave, respeite Retry-After, depois tente novamente deliberadamente |
| Validação de autenticação | Inicialização do cliente | Lança erro cedo se as credenciais estiverem ausentes |
| Loop de paginação | Listagem de propriedades/inquilinos | Incremente page até resposta vazia |
Saída
- Um cliente de API validado e vinculado a contrato com timeout centralizado e comportamento de classificação de erros
- Parâmetros de consulta limitados e respostas tipadas minimizadas para chamadores de serviço
- Resultados explícitos de limite de taxa e escrita desconhecida que exigem decisões de cursor/idempotência/reconciliação de propriedade do chamador
Exemplos
Para uma leitura de lista de propriedades, construa uma consulta com um tamanho de página limitado, execute-a através de safeCall e verifique os IDs de propriedade retornados e a contagem em relação a uma fixture sintética. Para uma mutação, persista uma chave de idempotência antes do despacho e trate um timeout ou 429 como uma condição de pausa/reconciliação, em vez de chamar a função novamente. Se a configuração do cliente, o esquema de resposta ou o resultado da escrita não forem verificados, pare o fluxo de trabalho e exiba um erro editado para o proprietário.
Recursos
Próximos Passos
Aplique os padrões em appfolio-core-workflow-a.