Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

为 AppFolio REST API 集成应用生产级模式。

tons-of-skills-marketplace 是什么?

该技能提供了一套用于 AppFolio 物业管理 REST API 集成的生产级模式。它围绕一个单例客户端构建,强制使用 HTTP 基本认证和客户端凭证,集中管理分页逻辑,并确保跨所有端点的一致错误处理。该技能提供了 TypeScript 实现,包括客户端创建、结构化错误封装(safeCall)、请求构建器(AppFolioQuery)以及用于属性、租户、租约和工单的完整响应类型。它通过合成固件支持单元测试,并在被限流或遇到未知故障时要求调用者负责重试逻辑,从而确保健壮、可审计的集成。

兼容平台✓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 基本认证,并以 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".

相关技能