94 lines
2.9 KiB
Markdown
94 lines
2.9 KiB
Markdown
---
|
||
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
|