Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

AppFolio REST API 統合のためのプロダクション対応パターンを適用します。

tons-of-skills-marketplace とは?

このスキルは、AppFolio プロパティ管理 REST API と統合するためのプロダクション対応パターンを提供します。HTTP Basic 認証とクライアント認証情報を使用し、プロパティ、テナント、リース、作業指示書に対して JSON レスポンスを返す AppFolio API を扱う際に、シングルトンクライアント、エラーハンドリング、ページネーション、リクエストビルダー、型付きレスポンス、テストユーティリティなどの実装パターンをまとめています。このスキルは、Claude Code や Cursor などの AI エージェントが、設定の注入、安全な呼び出し、レート制限処理、冪等性キー管理といったベストプラクティスに従って API クライアントを構築するための具体的なコード例(TypeScript)とガイダンスを提供します。また、認証情報の重複を防ぎ、一貫性のあるエラー処理とページネーションロジックを一元化することで、堅牢で保守性の高い統合を実現します。

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

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

ドキュメント

AppFolio SDK パターン

概要

AppFolio プロパティ管理 REST API のためのプロダクション対応パターン。AppFolio は HTTP Basic 認証とクライアント認証情報を使用し、プロパティ、テナント、リース、作業指示書に対して JSON レスポンスを返します。構造化されたシングルトンクライアントは、認証情報の重複を防ぎ、一貫性のあるエラー処理を強制し、すべてのプロパティ管理エンドポイントにわたってページネーションロジックを集中管理します。

前提条件

  • プロバイダーによって確認されたベース URL、認証方法、エンドポイントスコープ、およびターゲットポートフォリオのための管理されたシークレット注入パス。
  • すべての変更可能なサービスメソッドに対するスキーマ検証、リクエストタイムアウト、エンドポイント固有のレート制限、および冪等性キー。
  • 単体テスト用の合成フィクスチャ。本番のテナント、リース、および支払いペイロードが、デフォルトのモック、ログ、またはエラーメッセージの内容になってはなりません。

手順

  1. ランタイムごとに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, and BASE_URL required');
    _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', `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}`);
  }
}

リクエストビルダー

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 をインクリメントします

出力

  • 集中化されたタイムアウトとエラー分類動作を備えた、検証済みで契約にバインドされた 1 つの 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".

関連スキル