kiro-kit 0.1.3 → 0.2.1

package/dist/presets/fullstack/skills/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
+
+Kiro 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 .kiro/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/dist/presets/fullstack/skills/payment-integration/SKILL.md

@@ -1,7 +1,12 @@
----
-name: payment-integration
-description: Implement payment processing with Stripe, Polar, or SePay. Use when building checkout flows, subscriptions, usage-based billing, or handling payment webhooks.
----
+---
+name: payment-integration
+description: >-
+  Implement payment processing with Stripe, Polar, or SePay. Use when building
+  checkout flows, subscriptions, usage-based billing, or handling payment
+  webhooks.
+version: 1.0.0
+license: MIT
+---
 
 # Payment Integration
 

package/dist/presets/fullstack/skills/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