Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

AppFolio API バージョン間の移行とエンドポイント変更を処理します。

tons-of-skills-marketplace とは?

このスキルは、AppFolio 物件管理 API のバージョンアップグレードとマイグレーションを自動化します。現在の API バージョンを検出し、非推奨バージョンから最新バージョンへの移行を支援します。プロパティやテナントオブジェクトのスキーマ変更、エンドポイント URL の更新、ページネーションモデルの変更(オフセットベースからカーソルベースへ)など、破壊的変更に対応します。新しいバージョンでのリクエスト失敗時には自動的に以前のバージョンにロールバックする戦略を実装しており、統合テストスイートとの連携により安全な移行を実現します。主に TypeScript で記述された関数群で構成され、Claude Code や Cursor などの AI エージェントプラットフォーム上で動作します。

対応✓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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

AppFolio アップグレード&マイグレーション

概要

AppFolio 物件管理統合は、プラットフォームの進化に伴って変化するバージョン管理された REST API エンドポイントに依存しています。アップグレードにより、プロパティやテナントオブジェクトのフィールド名変更、ページネーションモデルの変更、ワークオーダーエンドポイントの非推奨化、基本認証フローの変更などが発生する可能性があります。このスキルは、現在の API バージョンを検出し、非推奨のレスポンス形状を新しいものにマッピングし、新しいバージョンで障害が発生した場合には自動的にロールバックします。

前提条件

  • 現在の API バージョンプレフィックスが文書化されていること(例: /api/v1/)
  • AppFolio API チェンジログおよびリリースノートへのアクセス
  • テスト用のプロパティおよびテナントデータを含むステージング環境
  • 環境変数に保存されたクライアント ID とシークレット
  • コアエンドポイントをカバーする既存の統合テストスイート

手順

  1. バージョン検出を実行し、アクティブな API バージョンと最新バージョンを比較します。
  2. AppFolio チェンジログを確認し、2 つのバージョン間の破壊的変更を特定します。
  3. プロパティおよびテナントのレスポンスオブジェクトにスキーマ移行変換を適用します。
  4. エンドポイント URL を古いバージョンプレフィックスから新しいものに更新します。
  5. 新しいバージョンで必要な場合、ページネーションをオフセットベースからカーソルベースに切り替えます。
  6. ステージング環境でスモークテストスイートを実行し、すべてのエンドポイントが応答することを確認します。
  7. ロールバック戦略を有効にして本番環境にデプロイします。
  8. 移行手順の見逃しを示す 410/401 レスポンスのエラーログを監視します。

出力

正常な移行後、スキルは以下を生成します。

  • 現在のバージョン、最新バージョン、非推奨バージョンを確認する VersionInfo オブジェクト
  • 新しいスキーマに準拠した変換済みプロパティおよびテナントオブジェクト
  • プロパティ、テナント、ワークオーダー、会計エンドポイントのスモークテスト結果
  • いずれかのエンドポイントが以前のバージョンにフォールバックした場合のロールバックログエントリ

バージョン検出

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

例

// Detect version and migrate if needed
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 を最新バージョンプレフィックスに更新
プロパティフィールド名の変更プロパティ同期で undefined 値migrateProperty 変換を適用
ページネーションオフセットの削除2ページ目以降で空の結果セットカーソルベースのページネーションに切り替え
認証ヘッダーの拒否アップグレード後に 401 Unauthorizedクライアントシークレットを再生成し、環境変数を更新
Webhook エンベロープの変更イベントハンドラーのパースエラー新しいエンベロープ用にペイロードパーサーを更新

リソース

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

関連スキル