AgentSkillsCN

polar-integration-validator

自主验证Polar.sh计费集成。检查webhook端点、签名验证、订阅中间件和环境配置。

SKILL.md
--- frontmatter
name: polar-integration-validator
description: Autonomous validation of Polar.sh billing integration. Checks webhook endpoints, signature verification, subscription middleware, and environment configuration.
triggers: ["webhook file changes", "subscription code changes", "wrangler.toml updates", "billing-related modifications"]

Polar Integration Validator SKILL

Activation Patterns

This SKILL automatically activates when:

  • •Files matching **/webhooks/polar.* are created/modified
  • •Files containing "subscription" or "polar" in path are modified
  • •wrangler.toml is updated
  • •Environment variable files (.dev.vars, .env) are modified
  • •Before deployment operations

Validation Rules

P1 - Critical (Block Operations)

Webhook Endpoint:

  • •✅ Webhook handler exists (server/api/webhooks/polar.ts or similar)
  • •✅ Signature verification implemented (polar.webhooks.verify)
  • •✅ All critical events handled: checkout.completed, subscription.created, subscription.updated, subscription.canceled

Environment Variables:

  • •✅ POLAR_ACCESS_TOKEN configured (check .dev.vars or secrets)
  • •✅ POLAR_WEBHOOK_SECRET in wrangler.toml

Database:

  • •✅ Users table has polar_customer_id column
  • •✅ Subscriptions table exists
  • •✅ Foreign key relationship configured

P2 - Important (Warn)

Event Handling:

  • •⚠️ subscription.past_due handler exists
  • •⚠️ Database updates in all event handlers
  • •⚠️ Error logging implemented

Subscription Middleware:

  • •⚠️ Subscription check function exists
  • •⚠️ Used on protected routes
  • •⚠️ Checks subscription_status === 'active'
  • •⚠️ Checks current_period_end not expired

P3 - Suggestions (Inform)

  • •ℹ️ Webhook event logging to database
  • •ℹ️ Customer creation helper function
  • •ℹ️ Subscription status caching
  • •ℹ️ Rate limiting on webhook endpoint

Validation Output

code
🔍 Polar.sh Integration Validation

✅ P1 Checks (Critical):
   ✅ Webhook endpoint exists
   ✅ Signature verification implemented
   ✅ Environment variables configured
   ✅ Database schema complete

⚠️ P2 Checks (Important):
   ⚠️ Missing subscription.past_due handler
   ✅ Subscription middleware exists
   ✅ Protected routes check subscription

ℹ️ P3 Suggestions:
   ℹ️ Consider adding webhook event logging
   ℹ️ Add rate limiting to webhook endpoint

📋 Summary: 1 warning found
💡 Run /es-billing-setup to fix issues

Escalation

Complex scenarios escalate to polar-billing-specialist agent:

  • •Custom webhook processing logic
  • •Multi-tenant subscription architecture
  • •Usage-based billing implementation
  • •Migration from other billing providers

Notes

  • •Runs automatically on relevant file changes
  • •Can block deployments with P1 issues
  • •Queries Polar MCP for product validation
  • •Integrates with /validate and /es-deploy commands