@hienlh/ppm 0.9.81 → 0.9.83

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

@@ -1,217 +0,0 @@
-# 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

@@ -1,156 +0,0 @@
----
-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

@@ -1,139 +0,0 @@
-# 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

@@ -1,99 +0,0 @@
-# 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.