Initial commit

skills/polar-integration-validator/SKILL.md

@@ -0,0 +1,93 @@
+---
+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
+
+```
+🔍 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