cokit-cli 1.0.1 → 1.0.3

package/skills/ck-payment-integration/README.md

@@ -0,0 +1,185 @@
+# Payment Integration Skill
+
+Comprehensive payment integration skill for SePay (Vietnamese payment gateway) and Polar (global SaaS monetization platform).
+
+## Features
+
+### SePay Integration
+- Vietnamese payment gateway with VietQR, NAPAS, bank transfers, and cards
+- 44+ supported banks
+- Webhook verification with API Key/OAuth2 authentication
+- QR code generation API
+- Order-based virtual accounts
+- SDK support for Node.js, PHP, and Laravel
+
+### Polar Integration
+- Global SaaS monetization platform
+- Merchant of Record (handles global tax compliance)
+- Subscription management with trials, upgrades, downgrades
+- Usage-based billing with events and meters
+- Automated benefit delivery (GitHub repos, Discord roles, license keys, files)
+- Customer self-service portal
+- Multi-language SDKs (TypeScript, Python, PHP, Go)
+- Framework adapters (Next.js, Laravel, Remix, etc.)
+
+## Structure
+
+```
+payment-integration/
+├── SKILL.md                      # Main skill definition
+├── README.md                     # This file
+├── references/                   # Progressive disclosure documentation
+│   ├── sepay/                   # SePay integration guides
+│   │   ├── overview.md          # Auth, capabilities, environments
+│   │   ├── api.md               # API endpoints and operations
+│   │   ├── webhooks.md          # Webhook setup and handling
+│   │   ├── sdk.md               # SDK usage (Node.js, PHP, Laravel)
+│   │   ├── qr-codes.md          # VietQR generation
+│   │   └── best-practices.md    # Security, patterns, monitoring
+│   └── polar/                   # Polar integration guides
+│       ├── overview.md          # Auth, MoR concept, environments
+│       ├── products.md          # Products, pricing, usage-based billing
+│       ├── checkouts.md         # Checkout flows and embedded checkout
+│       ├── subscriptions.md     # Lifecycle, upgrades, trials
+│       ├── webhooks.md          # Event handling and verification
+│       ├── benefits.md          # Automated benefit delivery
+│       ├── sdk.md               # Multi-language SDK usage
+│       └── best-practices.md    # Security, patterns, monitoring
+└── scripts/                      # Integration helper scripts
+    ├── sepay-webhook-verify.js   # SePay webhook verification
+    ├── polar-webhook-verify.js   # Polar webhook verification
+    ├── checkout-helper.js        # Checkout session generation
+    ├── test-scripts.js           # Test suite for all scripts
+    ├── package.json              # Node.js package configuration
+    └── .env.example              # Environment variable template
+```
+
+## Usage
+
+### Activate the Skill
+
+Claude Code will automatically activate this skill when you mention payment integration, subscriptions, webhooks, or platform-specific terms (SePay, Polar).
+
+### Manual Activation
+
+In conversations, simply reference the platforms:
+- "Implement SePay payment integration"
+- "Set up Polar subscriptions with usage-based billing"
+- "Create webhook handler for payment notifications"
+
+### Using Scripts
+
+**SePay Webhook Verification:**
+```bash
+cd %USERPROFILE%/.claude/skills/payment-integration/scripts
+node sepay-webhook-verify.js '{"id":12345,"gateway":"Vietcombank",...}'
+```
+
+**Polar Webhook Verification:**
+```bash
+node polar-webhook-verify.js '{"type":"order.paid","data":{...}}' base64secret
+```
+
+**Checkout Helper:**
+```bash
+# SePay
+node checkout-helper.js sepay '{"orderInvoiceNumber":"ORD001","orderAmount":100000,...}'
+
+# Polar
+node checkout-helper.js polar '{"productPriceId":"price_xxx","successUrl":"https://..."}'
+```
+
+**Run Tests:**
+```bash
+npm test
+```
+
+## Environment Variables
+
+Copy `.env.example` to `.env` and configure:
+
+```env
+# SePay
+SEPAY_MERCHANT_ID=SP-TEST-XXXXXXX
+SEPAY_SECRET_KEY=spsk_test_xxxxxxxxxxxxx
+SEPAY_ENV=sandbox
+SEPAY_WEBHOOK_API_KEY=your_key
+
+# Polar
+POLAR_ACCESS_TOKEN=polar_xxxxxxxxxxxxxxxx
+POLAR_SERVER=sandbox
+POLAR_WEBHOOK_SECRET=base64_secret
+```
+
+## Progressive Disclosure
+
+The skill uses progressive disclosure to minimize context usage:
+1. **SKILL.md** - Overview and quick reference (~99 lines)
+2. **references/** - Detailed guides loaded as needed (<100 lines each)
+3. **scripts/** - Executable helpers with embedded examples
+
+Load only the references you need for your current task.
+
+## Platform Selection Guide
+
+**Choose SePay for:**
+- Vietnamese market targeting
+- Bank transfer automation
+- Local payment methods
+- QR code payments (VietQR/NAPAS)
+- Direct bank monitoring
+
+**Choose Polar for:**
+- Global market
+- SaaS/subscription business
+- Usage-based billing
+- Automated benefit delivery
+- Tax compliance (Merchant of Record)
+- Customer self-service
+
+## Examples
+
+### SePay Payment Flow
+1. Load `references/sepay/overview.md` for authentication
+2. Load `references/sepay/sdk.md` for integration
+3. Use `checkout-helper.js` to generate payment form
+4. Load `references/sepay/webhooks.md` for notifications
+5. Use `sepay-webhook-verify.js` to verify authenticity
+
+### Polar Subscription Flow
+1. Load `references/polar/overview.md` for setup
+2. Load `references/polar/products.md` for pricing
+3. Load `references/polar/checkouts.md` for payment
+4. Load `references/polar/subscriptions.md` for lifecycle
+5. Load `references/polar/webhooks.md` for events
+6. Load `references/polar/benefits.md` for automation
+
+## Testing
+
+All scripts include comprehensive test coverage:
+- SePay webhook verification (with/without authentication)
+- Polar webhook signature validation
+- Checkout configuration generation
+- Error handling and edge cases
+
+Run `npm test` in the scripts directory to verify functionality.
+
+## Support
+
+### SePay
+- Docs: https://developer.sepay.vn/en
+- Email: info@sepay.vn
+- Hotline: 02873059589
+
+### Polar
+- Docs: https://polar.sh/docs
+- API Reference: https://polar.sh/docs/api-reference
+- GitHub: https://github.com/polarsource/polar
+
+## License
+
+MIT
+
+## Version
+
+1.0.0

package/skills/ck-payment-integration/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: 'ck-payment-integration'
+description: 'Implement payment integrations with SePay (Vietnamese payment gateway with VietQR, bank transfers, cards) and Polar (global SaaS monetization platform with subscriptions, usage-based billing, automated benefits). Use when integrating payment processing, implementing checkout flows, managing subscriptions, handling webhooks, processing bank transfers, generating QR codes, automating benefit delivery, or building billing systems. Supports authentication (API keys, OAuth2), product management, customer portals, tax compliance (Polar as MoR), and comprehensive SDK integrations (Node.js, PHP, Python, Go, Laravel, Next.js).'
+---
+
+# Payment Integration
+
+Implement payment processing with SePay (Vietnamese payments) and Polar (global SaaS monetization).
+
+## When to Use
+
+Use when implementing:
+- Payment gateway integration (checkout, processing)
+- Subscription management (trials, upgrades, billing)
+- Webhook handling (payment notifications)
+- QR code payments (VietQR, NAPAS)
+- Usage-based billing (metering, credits)
+- Automated benefit delivery (licenses, GitHub access, Discord roles)
+- Customer portals (self-service management)
+- Bank transfer automation (Vietnamese banks)
+- Product catalogs with pricing
+
+## Platform Selection
+
+**Choose SePay for:**
+- Vietnamese market (VND currency)
+- Bank transfer automation
+- VietQR/NAPAS payments
+- Local payment methods
+- Direct bank account monitoring
+
+**Choose Polar for:**
+- Global SaaS products
+- Subscription management
+- Usage-based billing
+- Automated benefits (GitHub, Discord, licenses)
+- Merchant of Record (tax compliance)
+- Digital product sales
+
+## Quick Reference
+
+### SePay Integration
+- **Overview & Auth**: `references/sepay/overview.md` - Platform capabilities, API/OAuth2 auth, supported banks
+- **API Reference**: `references/sepay/api.md` - Endpoints, transactions, bank accounts, virtual accounts
+- **Webhooks**: `references/sepay/webhooks.md` - Setup, payload structure, verification, retry logic
+- **SDK Usage**: `references/sepay/sdk.md` - Node.js, PHP, Laravel implementations
+- **QR Codes**: `references/sepay/qr-codes.md` - VietQR generation, templates, integration
+- **Best Practices**: `references/sepay/best-practices.md` - Security, patterns, monitoring
+
+### Polar Integration
+- **Overview & Auth**: `references/polar/overview.md` - Platform capabilities, authentication methods, MoR concept
+- **Products & Pricing**: `references/polar/products.md` - Product types, pricing models, usage-based billing
+- **Checkouts**: `references/polar/checkouts.md` - Checkout flows, embedded checkout, links
+- **Subscriptions**: `references/polar/subscriptions.md` - Lifecycle, upgrades, downgrades, trials
+- **Webhooks**: `references/polar/webhooks.md` - Event types, signature verification, monitoring
+- **Benefits**: `references/polar/benefits.md` - Automated delivery (GitHub, Discord, licenses, files)
+- **SDK Usage**: `references/polar/sdk.md` - TypeScript, Python, PHP, Go, framework adapters
+- **Best Practices**: `references/polar/best-practices.md` - Security, patterns, monitoring
+
+### Integration Scripts
+- **SePay Webhook Verification**: `scripts/sepay-webhook-verify.js` - Verify SePay webhook authenticity
+- **Polar Webhook Verification**: `scripts/polar-webhook-verify.js` - Verify Polar webhook signatures
+- **Checkout Helper**: `scripts/checkout-helper.js` - Generate checkout sessions for both platforms
+
+## Implementation Workflow
+
+### SePay Implementation
+1. Load `references/sepay/overview.md` for auth setup
+2. Load `references/sepay/api.md` or `references/sepay/sdk.md` for integration
+3. Load `references/sepay/webhooks.md` for payment notifications
+4. Use `scripts/sepay-webhook-verify.js` for webhook verification
+5. Load `references/sepay/best-practices.md` for production readiness
+
+### Polar Implementation
+1. Load `references/polar/overview.md` for auth and concepts
+2. Load `references/polar/products.md` for product setup
+3. Load `references/polar/checkouts.md` for payment flows
+4. Load `references/polar/webhooks.md` for event handling
+5. Use `scripts/polar-webhook-verify.js` for webhook verification
+6. Load `references/polar/benefits.md` if automating delivery
+7. Load `references/polar/best-practices.md` for production readiness
+
+## Key Capabilities
+
+**SePay:**
+- Payment gateway (QR, bank transfer, cards)
+- Bank account monitoring with webhooks
+- Order-based virtual accounts
+- VietQR generation API
+- 44+ Vietnamese banks supported
+- Rate limit: 2 calls/second
+
+**Polar:**
+- Merchant of Record (global tax compliance)
+- Subscription lifecycle management
+- Usage-based billing (events, meters)
+- Automated benefits (GitHub, Discord, licenses)
+- Customer portal (self-service)
+- Multi-language SDKs
+- Rate limit: 300 req/min
+
+## Instructions
+
+When implementing payment integration:
+
+1. **Identify platform** based on requirements (Vietnamese vs global, payment types)
+2. **Load relevant references** progressively as needed
+3. **Implement authentication** using platform-specific methods
+4. **Set up products/pricing** according to business model
+5. **Implement checkout flow** (hosted, embedded, or API-driven)
+6. **Configure webhooks** with proper verification
+7. **Handle payment events** (success, failure, refund)
+8. **Test thoroughly** in sandbox before production
+9. **Monitor and optimize** using platform analytics
+
+Load only the references needed for current implementation step to maintain context efficiency.

package/skills/ck-payment-integration/references/polar/benefits.md

@@ -0,0 +1,396 @@
+# Polar Benefits
+
+Automated benefit delivery system for digital products.
+
+## Philosophy
+
+Configure once, automatic delivery. Polar handles granting and revoking based on subscription state.
+
+## Benefit Types
+
+### 1. License Keys
+
+**Auto-generate unique keys with customizable branding.**
+
+**Create:**
+```typescript
+const benefit = await polar.benefits.create({
+  type: "license_keys",
+  organization_id: "org_xxx",
+  description: "Software License",
+  properties: {
+    prefix: "MYAPP",
+    expires: false,
+    activations: 1,
+    limit_usage: false
+  }
+});
+```
+
+**Validation API (unauthenticated):**
+```typescript
+const validation = await polar.licenses.validate({
+  key: "MYAPP-XXXX-XXXX-XXXX",
+  organization_id: "org_xxx"
+});
+
+if (validation.valid) {
+  // Grant access
+}
+```
+
+**Activation/Deactivation:**
+```typescript
+await polar.licenses.activate(licenseKey, {
+  label: "User's MacBook Pro"
+});
+
+await polar.licenses.deactivate(activationId);
+```
+
+**Auto-revoke:** On subscription cancellation or refund
+
+### 2. GitHub Repository Access
+
+**Auto-invite to private repos with permission management.**
+
+**Create:**
+```typescript
+const benefit = await polar.benefits.create({
+  type: "github_repository",
+  organization_id: "org_xxx",
+  description: "Access to private repo",
+  properties: {
+    repository_owner: "myorg",
+    repository_name: "private-repo",
+    permission: "pull" // or "push", "admin"
+  }
+});
+```
+
+**Multiple Repos:**
+```typescript
+{
+  properties: {
+    repositories: [
+      { owner: "myorg", name: "repo1", permission: "pull" },
+      { owner: "myorg", name: "repo2", permission: "push" }
+    ]
+  }
+}
+```
+
+**Behavior:**
+- Auto-invite on subscription activation
+- Permission managed by Polar
+- Auto-revoke on cancellation
+
+### 3. Discord Access
+
+**Server invites and role assignment.**
+
+**Create:**
+```typescript
+const benefit = await polar.benefits.create({
+  type: "discord",
+  organization_id: "org_xxx",
+  description: "Premium Discord role",
+  properties: {
+    guild_id: "123456789",
+    role_id: "987654321"
+  }
+});
+```
+
+**Multiple Roles:**
+```typescript
+{
+  properties: {
+    guild_id: "123456789",
+    roles: [
+      { role_id: "role1", name: "Premium" },
+      { role_id: "role2", name: "Supporter" }
+    ]
+  }
+}
+```
+
+**Requirements:**
+- Polar Discord app must be added to server
+- Configure in Polar dashboard
+
+**Behavior:**
+- Auto-invite to server
+- Assign roles automatically
+- Remove roles on cancellation
+
+### 4. Downloadable Files
+
+**Secure file delivery up to 10GB each.**
+
+**Create:**
+```typescript
+const benefit = await polar.benefits.create({
+  type: "downloadable",
+  organization_id: "org_xxx",
+  description: "Premium templates",
+  properties: {
+    files: [
+      { name: "template1.zip", size: 5000000 },
+      { name: "template2.psd", size: 10000000 }
+    ]
+  }
+});
+```
+
+**Upload Files:**
+- Via Polar dashboard
+- Secure storage
+- Access control
+
+**Customer Access:**
+- Download links in customer portal
+- Secure, time-limited URLs
+- Multiple files supported
+
+### 5. Meter Credits
+
+**Pre-purchased usage for usage-based billing.**
+
+**Create:**
+```typescript
+const benefit = await polar.benefits.create({
+  type: "custom",
+  organization_id: "org_xxx",
+  description: "10,000 API credits",
+  properties: {
+    meter_id: "meter_xxx",
+    credits: 10000
+  }
+});
+```
+
+**Automatic Application:**
+- Credits added on subscription start
+- Balance tracked via API
+- Depletes with usage
+
+**Balance Check:**
+```typescript
+const balance = await polar.meters.getBalance({
+  customer_id: "cust_xxx",
+  meter_id: "meter_xxx"
+});
+```
+
+### 6. Custom Benefits
+
+**Flexible placeholder for manual fulfillment.**
+
+**Create:**
+```typescript
+const benefit = await polar.benefits.create({
+  type: "custom",
+  organization_id: "org_xxx",
+  description: "Priority support via email",
+  properties: {
+    note: "Email support@example.com with your order ID for priority support"
+  }
+});
+```
+
+**Use Cases:**
+- Cal.com booking links
+- Email support access
+- Community forum access
+- Manual onboarding
+
+## Benefit Grants
+
+**Link between customer and benefit.**
+
+### States
+- `created` - Grant created
+- `active` - Benefit delivered
+- `revoked` - Access removed
+
+### Webhooks
+- `benefit_grant.created` - Grant created
+- `benefit_grant.updated` - Status changed
+- `benefit_grant.revoked` - Access revoked
+
+### Auto-revoke Triggers
+- Subscription canceled
+- Subscription revoked
+- Refund processed
+- Product changed (if benefit not on new product)
+
+### Querying Grants
+```typescript
+const grants = await polar.benefitGrants.list({
+  customer_id: "cust_xxx",
+  benefit_id: "benefit_xxx",
+  is_granted: true
+});
+```
+
+## Attaching Benefits to Products
+
+### Via API
+```typescript
+await polar.products.updateBenefits(productId, {
+  benefits: [benefitId1, benefitId2, benefitId3]
+});
+```
+
+### Via Dashboard
+1. Navigate to product
+2. Benefits tab
+3. Select benefits to attach
+4. Save
+
+### Order
+- Benefits granted in order attached
+- Customers see in that order
+- Reorder via dashboard or API
+
+## Customer Experience
+
+### Viewing Benefits
+- Customer portal shows all active benefits
+- Clear instructions for each type
+- Download links for files
+- License keys displayed
+
+### Accessing Benefits
+```typescript
+// Generate customer portal link
+const session = await polar.customerSessions.create({
+  external_customer_id: userId
+});
+
+// Customer sees:
+// - Active subscriptions
+// - Granted benefits
+// - Download links
+// - License keys
+// - Instructions
+```
+
+## Implementation Patterns
+
+### License Key Validation
+```typescript
+// In your application
+async function validateLicense(key) {
+  try {
+    const result = await polar.licenses.validate({
+      key: key,
+      organization_id: process.env.POLAR_ORG_ID
+    });
+
+    if (!result.valid) {
+      return { valid: false, reason: 'Invalid license' };
+    }
+
+    if (result.limit_usage && result.usage >= result.limit_usage) {
+      return { valid: false, reason: 'Usage limit exceeded' };
+    }
+
+    return { valid: true, customer: result.customer };
+  } catch (error) {
+    console.error('License validation failed:', error);
+    return { valid: false, reason: 'Validation error' };
+  }
+}
+```
+
+### GitHub Access Check
+```typescript
+// Listen to benefit grant webhook
+app.post('/webhook/polar', async (req, res) => {
+  const event = validateEvent(req.body, req.headers, secret);
+
+  if (event.type === 'benefit_grant.created') {
+    const grant = event.data;
+
+    if (grant.benefit.type === 'github_repository') {
+      // Update user's GitHub access in your system
+      await updateGitHubAccess(grant.customer.external_id, true);
+    }
+  }
+
+  res.json({ received: true });
+});
+```
+
+### Discord Role Sync
+```typescript
+// Monitor benefit grants
+if (event.type === 'benefit_grant.created') {
+  const grant = event.data;
+
+  if (grant.benefit.type === 'discord') {
+    // Notify user to connect Discord
+    await sendDiscordInvite(grant.customer.email);
+  }
+}
+
+if (event.type === 'benefit_grant.revoked') {
+  const grant = event.data;
+
+  if (grant.benefit.type === 'discord') {
+    // Roles removed automatically by Polar
+    await notifyRoleRemoval(grant.customer.external_id);
+  }
+}
+```
+
+## Best Practices
+
+1. **Benefit Selection:**
+   - Choose appropriate benefit types
+   - Consider automation capabilities
+   - Plan for revocation scenarios
+
+2. **License Keys:**
+   - Set appropriate activation limits
+   - Monitor usage patterns
+   - Provide clear validation errors
+   - Allow customers to manage activations
+
+3. **GitHub Access:**
+   - Set minimum required permissions
+   - Use separate repos for different tiers
+   - Monitor repository access
+   - Communicate access removal
+
+4. **Discord Roles:**
+   - Clear role hierarchy
+   - Meaningful role names
+   - Separate roles per product tier
+   - Welcome messages for new members
+
+5. **Files:**
+   - Organize files clearly
+   - Provide README/instructions
+   - Keep files updated
+   - Version control important files
+
+6. **Credits:**
+   - Clear credit value communication
+   - Usage tracking and display
+   - Alerts near depletion
+   - Easy credit top-up
+
+7. **Custom Benefits:**
+   - Clear, actionable instructions
+   - Provide contact information
+   - Set expectations for timing
+   - Track manual fulfillment
+
+8. **Customer Communication:**
+   - Welcome email with benefit access info
+   - Instructions for each benefit type
+   - Support contact for issues
+   - Revocation warnings before cancellation