Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

在 AppFolio API 版本之間遷移,並處理端點變更。

tons-of-skills-marketplace 是什麼?

此技能旨在協助開發者自動處理 AppFolio 物業管理整合中的 API 版本升級與遷移。它能夠自動偵測當前使用的 API 版本,比對最新版本,並識別已棄用的版本。技能會自動套用屬性(Property)和租戶(Tenant)物件的結構變更轉換,將分頁模型從偏移量(offset)切換為游標(cursor)方式,並處理端點 URL 的更新。若新版 API 端點回應 404 或 410 錯誤,技能會自動回退至舊版,確保服務不中斷。其涵蓋了從版本偵測、結構遷移、回退策略到錯誤處理的完整流程,並可整合測試套件進行驗證,顯著降低手動遷移的風險與工作量。

相容平台✓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-upgrade-migration

在你喜歡的 AI 中提問

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

說明文件

AppFolio 升級與遷移

概述

AppFolio 物業管理整合依賴於會隨平台演進的版本化 REST API 端點。 升級可能會重新命名物件(property 和 tenant)上的欄位、 變更分頁模型、棄用工單端點,以及修改基本認證流程。 此技能會偵測您目前的 API 版本,將已棄用的回傳結構對應到替代方案, 並在新版本失敗時自動回滾。

先決條件

  • 已記錄目前 API 版本前綴(例如 /api/v1/)
  • 可存取 AppFolio API 變更日誌與發行說明
  • 具有測試用 property 和 tenant 資料的暫存環境
  • 將 Client ID 和 secret 儲存在環境變數中
  • 現有的涵蓋核心端點的整合測試套件

操作說明

  1. 執行版本偵測,將您使用的 API 版本與最新版本進行比較。
  2. 檢閱 AppFolio 變更日誌,找出兩個版本之間的破壞性變更。
  3. 對 property 和 tenant 回應物件套用結構遷移轉換。
  4. 將端點 URL 從舊版本前綴更新為新版本前綴。
  5. 如果新版本要求,將分頁從偏移量(offset)切換為游標(cursor)方式。
  6. 針對暫存環境執行煙霧測試套件,以驗證所有端點皆正常回應。
  7. 啟用回滾策略後,部署至正式環境。
  8. 監控錯誤日誌中代表遺漏遷移步驟的 410/401 回應。

輸出

成功遷移後,此技能會產生:

  • 一個 VersionInfo 物件,確認目前版本、最新版本和已棄用版本
  • 符合新結構的轉換後 property 與 tenant 物件
  • 針對 property、tenant、工單和會計端點的煙霧測試結果
  • 若任何端點回退至前一版本時,產生的回滾日誌條目

版本偵測

interface VersionInfo { current: string; latest: string; deprecated: string[]; }

async function detectApiVersion(baseUrl: string, headers: Record<string, string>): Promise<VersionInfo> {
  const res = await fetch(`${baseUrl}/api/status`, { headers });
  const body = await res.json();
  const current = res.headers.get("X-AppFolio-Api-Version") ?? body.api_version;
  const deprecated: string[] = body.deprecated_versions ?? [];
  if (deprecated.includes(current)) {
    console.warn(`Version ${current} is deprecated. Migrate to ${body.latest_version}.`);
  }
  return { current, latest: body.latest_version, deprecated };
}

結構遷移

interface LegacyProperty { address_line1: string; unit_count: number; mgr_id: string; }
interface CurrentProperty { street_address: string; total_units: number; manager_id: string; }

function migrateProperty(old: LegacyProperty): CurrentProperty {
  return { street_address: old.address_line1, total_units: old.unit_count, manager_id: old.mgr_id };
}

interface LegacyTenant { lease_end: string; balance_due: number; }
interface CurrentTenant { lease_expiry_date: string; outstanding_balance: number; }

function migrateTenant(old: LegacyTenant): CurrentTenant {
  return { lease_expiry_date: old.lease_end, outstanding_balance: old.balance_due };
}

回滾策略

async function versionAwareRequest(
  baseUrl: string, path: string, headers: Record<string, string>,
  targetVersion: string, fallbackVersion: string
): Promise<any> {
  const res = await fetch(`${baseUrl}/api/${targetVersion}${path}`, { headers });
  if (res.status === 410 || res.status === 404) {
    console.warn(`${targetVersion} rejected; falling back to ${fallbackVersion}`);
    const fallback = await fetch(`${baseUrl}/api/${fallbackVersion}${path}`, { headers });
    if (!fallback.ok) throw new Error(`Fallback failed: ${fallback.status}`);
    return fallback.json();
  }
  if (!res.ok) throw new Error(`Request failed: ${res.status}`);
  return res.json();
}

範例

// 偵測版本並在需要時遷移
const info = await detectApiVersion("https://acme.appfolio.com", authHeaders);
if (info.deprecated.includes(info.current)) {
  const oldProps = await fetchLegacyProperties();
  const migrated = oldProps.map(migrateProperty);
  await smokeTestEndpoints("https://acme.appfolio.com", authHeaders);
}

錯誤處理

遷移問題症狀修復方式
已棄用的版本前綴每次請求都收到 410 Gone將基礎 URL 更新為最新版本前綴
已重新命名的 property 欄位property 同步中出現 undefined 值套用 migrateProperty 轉換
已移除的分頁偏移量第一頁之後的結果集為空切換為游標式分頁
認證標頭被拒絕升級後出現 401 Unauthorized重新產生客戶端金鑰,更新環境變數
Webhook 信封變更事件處理器解析錯誤更新用於新信封的 payload 解析器

資源

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".

相關技能