@hienlh/ppm 0.9.79 → 0.9.81

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

@@ -0,0 +1,217 @@
+# Payment Integration Skill
+
+Comprehensive payment integration skill for SePay (Vietnamese payment gateway), Polar (global SaaS monetization platform), and Stripe (global payment infrastructure).
+
+## 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.)
+
+### Stripe Integration
+- Global payment infrastructure
+- CheckoutSessions, PaymentIntents, SetupIntents APIs
+- Billing and subscriptions at scale
+- Connect for marketplaces and platforms
+- Payment Element for custom checkout experiences
+- Multi-language SDKs (Node.js, Python, Ruby, PHP, Java, Go, .NET)
+- Best practices for integration design and API version upgrades
+
+## 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
+│   └── stripe/                  # Stripe integration guides
+│       ├── stripe-best-practices.md  # Integration design, API selection
+│       └── stripe-upgrade.md         # API versions, SDK upgrades
+└── 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 $HOME/.opencode/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
+
+**Choose Stripe for:**
+- Global payment infrastructure
+- Enterprise-grade payment processing
+- Connect platforms (marketplaces)
+- Billing/subscriptions at scale
+- Custom checkout experiences (Payment Element)
+- Maximum payment method coverage
+
+## 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
+
+### Stripe Integration Flow
+1. Load `references/stripe/stripe-best-practices.md` for integration design
+2. Choose: Checkout (hosted/embedded) or Payment Element
+3. Use CheckoutSessions API for most use cases
+4. Load `references/stripe/stripe-upgrade.md` when upgrading API versions
+
+## 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
+
+### Stripe
+- Docs: https://docs.stripe.com
+- API Reference: https://docs.stripe.com/api
+- Changelog: https://docs.stripe.com/changelog
+- Go Live Checklist: https://docs.stripe.com/get-started/checklist/go-live
+
+## License
+
+MIT
+
+## Version
+
+1.1.0

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

@@ -0,0 +1,156 @@
+---
+name: ck:payment-integration
+description: Integrate payments with SePay (VietQR), Polar (SaaS subscriptions), Stripe (global payments). Use for checkout, webhooks, QR codes, subscriptions, currency conversion, multi-provider order management, commission systems.
+argument-hint: "[provider] [task]"
+license: MIT
+metadata:
+  author: claudekit
+  version: "2.0.0"
+---
+
+# Payment Integration
+
+Production-proven payment processing patterns with SePay (Vietnamese bank transfers), Polar (global SaaS monetization), and Stripe (global payment infrastructure). Includes multi-provider order management, currency conversion, commission systems, and webhook handling.
+
+## When to Use
+
+Use when implementing:
+- Payment gateway integration (checkout, processing)
+- Subscription management (trials, upgrades, billing)
+- Webhook handling (payment notifications, idempotency)
+- 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
+- Multi-provider order management (Polar + SePay)
+- Currency conversion (USD/VND with fallback chains)
+- Commission and referral systems
+- Revenue tracking and maintainer payouts
+- Discount management and cross-provider sync
+
+## 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
+
+**Choose Stripe for:**
+- Global payment infrastructure
+- Enterprise-grade payment processing
+- Connect platforms (marketplaces)
+- Billing/subscriptions at scale
+- Custom checkout experiences
+- Payment Element integrations
+
+## 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` - Transaction parsing, order matching, webhook handling, currency conversion, invoice generation, error handling
+
+### 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` - SDK initialization, checkout flows, webhooks, fee calculations, discount management, error handling
+
+### Multi-Provider Patterns
+- **Order Management**: `references/multi-provider-order-management-patterns.md` - Unified order schema, currency conversion, commissions, revenue tracking, refunds, webhook idempotency
+
+### Stripe Integration
+- **Full Documentation**: https://docs.stripe.com/llms.txt - Complete Stripe docs for LLMs
+- **SDKs**: `references/stripe/stripe-sdks.md` - Node.js, Python, Ruby, Go, PHP, Java, .NET setup & usage
+- **Stripe.js**: `references/stripe/stripe-js.md` - Client-side Elements, Payment Element, Embedded Checkout
+- **CLI**: `references/stripe/stripe-cli.md` - Webhook testing, logs, fixtures, local development
+- **Best Practices**: `references/stripe/stripe-best-practices.md` - Integration design, API selection, Checkout vs Payment Element
+- **Upgrading**: `references/stripe/stripe-upgrade.md` - API versions, SDK upgrades, Stripe.js versioning
+- **External Docs**: https://docs.stripe.com/sdks | https://docs.stripe.com/js | https://docs.stripe.com/cli
+
+### 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
+
+### Stripe Implementation
+1. Load `references/stripe/stripe-best-practices.md` for integration design
+2. Load `references/stripe/stripe-sdks.md` for server-side SDK setup
+3. Load `references/stripe/stripe-js.md` for client-side Elements/Checkout
+4. Use `stripe listen` via CLI for local webhook testing (`references/stripe/stripe-cli.md`)
+5. Choose integration: Checkout (hosted/embedded) or Payment Element
+6. Use CheckoutSessions API for most payment flows
+7. Use Billing APIs for subscriptions (combine with Checkout)
+8. Load `references/stripe/stripe-upgrade.md` when upgrading API versions
+
+## 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
+
+**Stripe:**
+- Global payment infrastructure
+- CheckoutSessions, PaymentIntents, SetupIntents APIs
+- Billing/subscriptions with trials, prorations
+- Connect for marketplaces/platforms
+- Payment Element for custom UI
+- Multi-language SDKs
+
+## Instructions
+
+1. Identify platform (Vietnamese → SePay, global SaaS → Polar/Stripe)
+2. Load relevant references progressively
+3. Implement auth → products → checkout → webhooks → events
+4. Test in sandbox, then production
+5. Load only needed references to maintain context efficiency

package/.opencode/skills/payment-integration/references/creem/api.md

@@ -0,0 +1,139 @@
+# Creem.io API Reference
+
+## Checkout Sessions
+
+### Create Checkout Session
+
+```javascript
+// POST /v1/checkout/sessions
+const session = await creem.checkout.sessions.create({
+  product_id: 'prod_xxx',
+  success_url: 'https://example.com/success',
+  cancel_url: 'https://example.com/cancel',
+  customer_email: 'user@example.com', // Optional
+  metadata: { order_id: '123' }       // Optional
+});
+// Returns: { url: 'https://checkout.creem.io/xxx', id: 'cs_xxx' }
+```
+
+## Products
+
+### Create Product
+
+```javascript
+// POST /v1/products
+const product = await creem.products.create({
+  name: 'Pro Plan',
+  description: 'Full access to all features',
+  price: 2900,           // Amount in cents
+  currency: 'usd',
+  recurring: {           // Optional - for subscriptions
+    interval: 'month',
+    interval_count: 1
+  }
+});
+```
+
+### Retrieve Product
+
+```javascript
+// GET /v1/products/:id
+const product = await creem.products.retrieve('prod_xxx');
+```
+
+## Transactions
+
+### Retrieve Transaction
+
+```javascript
+// GET /v1/transactions/:id
+const transaction = await creem.transactions.retrieve('txn_xxx');
+```
+
+### List Transactions
+
+```javascript
+// GET /v1/transactions
+const transactions = await creem.transactions.list({
+  customer_id: 'cus_xxx',      // Optional filter
+  product_id: 'prod_xxx',      // Optional filter
+  status: 'completed',         // Optional filter
+  limit: 25,
+  starting_after: 'txn_xxx'    // Pagination cursor
+});
+```
+
+## Customers
+
+### Retrieve Customer
+
+```javascript
+// GET /v1/customers/:id
+const customer = await creem.customers.retrieve('cus_xxx');
+
+// GET /v1/customers/email/:email
+const customer = await creem.customers.retrieveByEmail('user@example.com');
+```
+
+### List Customers
+
+```javascript
+// GET /v1/customers
+const customers = await creem.customers.list({
+  limit: 25,
+  starting_after: 'cus_xxx'
+});
+```
+
+### Generate Portal Link
+
+```javascript
+// POST /v1/customers/:id/portal
+const portal = await creem.customers.createPortalSession('cus_xxx');
+// Returns: { url: 'https://portal.creem.io/xxx' }
+```
+
+## Discount Codes
+
+### Create Discount
+
+```javascript
+// POST /v1/discounts
+const discount = await creem.discounts.create({
+  code: 'LAUNCH20',
+  type: 'percentage',    // or 'fixed'
+  value: 20,             // 20% or 20 cents
+  expires_at: '2024-12-31T23:59:59Z',
+  max_redemptions: 100   // Optional
+});
+```
+
+### Retrieve Discount
+
+```javascript
+// GET /v1/discounts/:code
+const discount = await creem.discounts.retrieve('LAUNCH20');
+```
+
+### Delete Discount
+
+```javascript
+// DELETE /v1/discounts/:code
+await creem.discounts.delete('LAUNCH20');
+```
+
+## Error Handling
+
+```javascript
+try {
+  const session = await creem.checkout.sessions.create({...});
+} catch (error) {
+  if (error.type === 'invalid_request_error') {
+    console.error('Invalid parameters:', error.message);
+  } else if (error.type === 'authentication_error') {
+    console.error('Invalid API key');
+  } else if (error.type === 'rate_limit_error') {
+    console.error('Rate limited, retry after:', error.retry_after);
+  }
+}
+```

package/.opencode/skills/payment-integration/references/creem/checkouts.md

@@ -0,0 +1,99 @@
+# Creem.io Checkouts
+
+## Checkout Options
+
+1. **Programmatic Sessions** - Full API control
+2. **Checkout Links** - No-code, shareable URLs
+3. **Storefronts** - Hosted product pages
+
+## Create Checkout Session
+
+```javascript
+const session = await creem.checkout.sessions.create({
+  product_id: 'prod_xxx',
+  success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
+  cancel_url: 'https://example.com/cancel',
+
+  // Optional parameters
+  customer_email: 'user@example.com',
+  customer_id: 'cus_xxx',           // Existing customer
+  quantity: 1,                       // For seat-based products
+  discount_code: 'LAUNCH20',         // Pre-apply discount
+  metadata: {
+    order_id: '123',
+    referral_code: 'abc'
+  },
+
+  // Custom fields
+  custom_fields: [
+    { key: 'company', label: 'Company Name', required: true }
+  ]
+});
+
+// Redirect user to checkout
+redirect(session.url);
+```
+
+## Checkout Customization
+
+Configure in dashboard or via API:
+
+- **Branding**: Logo, colors, themes
+- **Email Receipts**: Custom templates
+- **Localization**: Auto-detect or force language (42 supported)
+- **Custom Fields**: Collect additional data
+
+## Retrieve Session
+
+```javascript
+// GET /v1/checkout/sessions/:id
+const session = await creem.checkout.sessions.retrieve('cs_xxx');
+// Returns: { id, status, customer_id, product_id, amount, metadata, ... }
+```
+
+## Success URL Parameters
+
+Creem replaces `{CHECKOUT_SESSION_ID}` in success URL:
+
+```javascript
+// Frontend: parse session ID from URL
+const urlParams = new URLSearchParams(window.location.search);
+const sessionId = urlParams.get('session_id');
+
+// Backend: verify and fulfill
+const session = await creem.checkout.sessions.retrieve(sessionId);
+if (session.status === 'complete') {
+  await fulfillOrder(session);
+}
+```
+
+## No-Code Checkout Links
+
+Create in dashboard - shareable URLs for any product. Good for:
+- Social media links
+- Email campaigns
+- Quick sales without integration
+
+## Storefronts
+
+Hosted product pages - display multiple products without custom website:
+
+1. Configure storefront in dashboard
+2. Add products to display
+3. Share storefront URL
+4. Customers browse and checkout
+
+## Cart Abandonment Recovery
+
+Enable in dashboard - automatic emails sent when checkout abandoned:
+- Configurable delay before sending
+- Customizable email content
+- Include discount code incentive
+
+## Embedding (Coming)
+
+For embedded checkout in your site, see SDK adapters:
+- Next.js Adapter
+- React components
+
+See `references/creem/sdk.md` for implementation details.