Communitygithub.com

AppFolio SDK 模式

為 AppFolio REST API 整合提供生產就緒的模式。

AppFolio SDK 模式 是什麼?

這個技能提供一組生產就緒的模式,用於與 AppFolio 物業管理 REST API 進行整合。它引入了一個結構化的單例客戶端,可集中管理認證(HTTP Basic Auth)、錯誤處理和分頁邏輯,從而防止憑證散落各處,並確保所有物業管理端點(如物業、租戶、租約和工單)的行為一致。該技能包括 TypeScript 實作,例如一個具備逾時和錯誤分類功能的 Axios 客戶端、一個用於標準化 API 錯誤的 `safeCall` 包裝器、一個帶有可鏈式查詢參數(如狀態和分頁)的 `Request Builder`,以及用於定義物業、租戶、租約和工單形狀的回應類型。此外,還包含測試工具,例如用於建立合成測試資料的 `mockProperty` 和 `mockLease` 工廠函式。此技能的主要價值在於為開發者提供一個可重複使用、經過驗證的基礎,用於建立可靠且可維護的 AppFolio API 整合,並附有明確的錯誤處理、速率限制和冪等性準則。支援的平台包括任何可使用 TypeScript 的 AI 代理或開發環境。它的運作方式是透過 SKILL.md 文件提供結構化指導和程式碼範例,開發者可以將其直接套用到自己的專案中。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/HEAD/plugins/saas-packs/appfolio-pack/skills/appfolio-sdk-patterns

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

AppFolio SDK 模式 是做什麼的?

概述

適用於 AppFolio 物業管理 REST API 的生產就緒模式。AppFolio 使用 HTTP Basic Auth 搭配客戶端憑證,並針對物業、租戶、租約和工單回傳 JSON 回應。一個結構化的單例客戶端可防止憑證散落、強制執行一致的錯誤處理,並將所有物業管理端點的分頁邏輯集中管理。

先決條件

  • 供應商已驗證的基礎 URL、驗證方法、端點範圍,以及目標投資組合的受管密碼注入路徑。
  • 所有具備突變能力的服務方法都需進行架構驗證、設定請求逾時、端點特定的速率限制,以及使用冪等金鑰。
  • 用於單元測試的合成測試資料;不得將生產環境的租戶、租約和付款負載作為預設的模擬資料、日誌或錯誤訊息內容。

指示

  1. 每個執行階段建立一個綁定合約的客戶端,並在請求開始前拒絕缺少或無效的配置。
  2. 在服務邊界驗證查詢邊界和回應形狀,然後僅將最小化的型別欄位傳遞給呼叫者。
  3. 將分類後的 429 或未知寫入失敗回傳給呼叫者;僅在呼叫者記錄游標/金鑰和延遲後,才重試冪等操作。
  4. 將寫入工作流程保留在明確的授權、稽核和對帳控制之後,而不是將其嵌入通用的 SDK 便捷輔助函式中。

單例客戶端

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 和 BASE_URL');
    _client = axios.create({ baseURL, auth: { username: clientId, password: clientSecret }, timeout: 30000 });
  }
  return _client;
}

錯誤包裝器

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', `請在 ${retryAfter ?? '供應商指定的延遲'} 後重試;請勿自動重播未知的寫入操作`);
    }
    if (status === 401) throw new AppFolioError(401, 'AUTH', '無效的 APPFOLIO_CLIENT_ID 或 SECRET');
    throw new AppFolioError(status, 'API_ERROR', `${operation} 失敗 [${status}]: ${err.message}`);
  }
}

請求建構器

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; }
}
// 使用方式:new AppFolioQuery().status('active').perPage(50).build();

回應類型

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';
}

測試工具

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 };
}

錯誤處理

模式使用時機範例
safeCall 包裝器所有 API 呼叫防止未捕獲的 4xx/5xx 導致流程崩潰
呼叫者擁有的 429 重試受速率限制的冪等批次讀取保留游標/金鑰,遵守 Retry-After,然後審慎重試
驗證驗證客戶端初始化若缺少憑證則提前拋出錯誤
分頁迴圈列出物業/租戶遞增 page 直到回傳空回應

輸出

  • 一個經過驗證、綁定合約的 API 客戶端,具備集中的逾時和錯誤分類行為
  • 為服務呼叫者提供有界的查詢參數和最小化的型別回應
  • 明確的速率限制和未知寫入結果,要求呼叫者做出游標/冪等性/對帳決策

範例

對於物業列表讀取,使用設定了上限頁面大小的查詢建構器,透過 safeCall 執行,並針對合成測試資料驗證回傳的物業 ID 和計數。對於突變操作,在分派前先保存一個冪等金鑰,並將逾時或 429 視為暫停/對帳條件,而不是直接再次呼叫函式。如果客戶端配置、回應架構或寫入結果未經驗證,請停止工作流程並向擁有者顯示一個經過編輯的錯誤訊息。

資源

後續步驟

在 appfolio-core-workflow-a 中套用這些模式。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page for positioning, plan a conversion-optimized page layout, or design a launch page. Examples: "landing page for product launch", "conversion-optimized layout for SaaS

jeremylongshore/tons-of-skills-marketplace

Use when asked to design growth-optimized landing pages, activation funnel layouts, or experiment-friendly page structures. Examples: "growth-optimized landing", "activation funnel layout", "A/B testable page

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page, design page layout for conversion, or plan landing page information architecture. Examples: "landing page structure for SaaS", "conversion-optimized layout

jeremylongshore/tons-of-skills-marketplace

Generate polished demo videos from a single prompt. Use when the user asks to create a demo video, product walkthrough, feature showcase, or animated presentation. Trigger with "make a demo video", "create a product video", "demo walkthrough", or "feature showcase video".

jeremylongshore/tons-of-skills-marketplace

Track cryptocurrency portfolio with real-time valuations, allocation analysis, and P&L tracking. Use when checking portfolio value, viewing holdings breakdown, analyzing allocations, or exporting portfolio data. Trigger with phrases like "show my portfolio", "check crypto holdings", "portfolio allocation", "track my crypto", or "export portfolio".

jeremylongshore/tons-of-skills-marketplace

Runs the full release workflow for the current project. Commits any uncommitted changes, pushes to remote, creates and merges a PR if on a feature branch, determines the next semver version from conventional commits, creates an annotated git tag and GitHub release with generated notes, cleans up merged branches, and returns to a clean main. Use when the user says promote, ship, release, commit and push, tag and release, or get back to main.

jeremylongshore/tons-of-skills-marketplace

Agent skill at plugins/productivity/content-multiplier/skills/channel-formats/SKILL.md

jeremylongshore/tons-of-skills-marketplace

Operate an evidence-backed editorial queue, balance topic and format coverage, schedule approved drafts, and reconcile backlog state with the publishing system. Use when choosing or scheduling the next blog work. Trigger with "show the editorial calendar" or "pick the next topic".

jeremylongshore/tons-of-skills-marketplace

Configure CI/CD pipeline for AppFolio property management integrations. Trigger: "appfolio CI".

jeremylongshore/tons-of-skills-marketplace

Diagnose and fix common AppFolio API integration errors. Trigger: "appfolio error".

jeremylongshore/tons-of-skills-marketplace

Build property management dashboard with AppFolio API data. Trigger: "appfolio property dashboard".

jeremylongshore/tons-of-skills-marketplace

Automate tenant management and lease operations with AppFolio. Trigger: "appfolio tenant management".

jeremylongshore/tons-of-skills-marketplace

Collect AppFolio API debug evidence for support tickets. Trigger: "appfolio debug".

jeremylongshore/tons-of-skills-marketplace

Deploy AppFolio integration service to cloud infrastructure. Trigger: "deploy appfolio".

jeremylongshore/tons-of-skills-marketplace

Query AppFolio properties, units, and tenants via REST API. Trigger: "appfolio hello world".

jeremylongshore/tons-of-skills-marketplace

Configure AppFolio Stack API authentication with OAuth 2.0. Use when setting up property management API access, registering as an AppFolio Stack partner, or configuring client credentials for API calls. Trigger: "install appfolio", "setup appfolio", "appfolio auth", "appfolio API key".

jeremylongshore/tons-of-skills-marketplace

Set up local development for AppFolio property management API integration. Trigger: "appfolio local dev".

jeremylongshore/tons-of-skills-marketplace

Production readiness checklist for AppFolio integrations. Trigger: "appfolio production checklist".

jeremylongshore/tons-of-skills-marketplace

Handle AppFolio API rate limits with throttling and backoff. Trigger: "appfolio rate limit".

jeremylongshore/tons-of-skills-marketplace

Reference architecture for AppFolio property management integration. Trigger: "appfolio architecture".

相關技能