@stella-studio/ck 1.0.0

package/.claude/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/.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
+
+**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/.claude/skills/payment-integration/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: payment-integration
+description: Integrate payments with SePay (VietQR), Polar, Stripe, Paddle (MoR subscriptions), Creem.io (licensing). Checkout, webhooks, subscriptions, QR codes, multi-provider orders.
+version: 2.2.0
+license: MIT
+---
+
+# Payment Integration
+
+Production-proven payment processing with SePay (Vietnamese banks), Polar (global SaaS), Stripe (global infrastructure), Paddle (MoR subscriptions), and Creem.io (MoR + licensing).
+
+## When to Use
+
+- Payment gateway integration (checkout, processing)
+- Subscription management (trials, upgrades, billing)
+- Webhook handling (notifications, idempotency)
+- QR code payments (VietQR, NAPAS)
+- Software licensing (device activation)
+- Multi-provider order management
+- Revenue splits and commissions
+
+## Platform Selection
+
+| Platform | Best For |
+|----------|----------|
+| **SePay** | Vietnamese market, VND, bank transfers, VietQR |
+| **Polar** | Global SaaS, subscriptions, automated benefits (GitHub/Discord) |
+| **Stripe** | Enterprise payments, Connect platforms, custom checkout |
+| **Paddle** | MoR subscriptions, global tax compliance, churn prevention |
+| **Creem.io** | MoR + licensing, revenue splits, no-code checkout |
+
+## Quick Reference
+
+### SePay
+- `references/sepay/overview.md` - Auth, supported banks
+- `references/sepay/api.md` - Endpoints, transactions
+- `references/sepay/webhooks.md` - Setup, verification
+- `references/sepay/sdk.md` - Node.js, PHP, Laravel
+- `references/sepay/qr-codes.md` - VietQR generation
+- `references/sepay/best-practices.md` - Production patterns
+
+### Polar
+- `references/polar/overview.md` - Auth, MoR concept
+- `references/polar/products.md` - Pricing models
+- `references/polar/checkouts.md` - Checkout flows
+- `references/polar/subscriptions.md` - Lifecycle management
+- `references/polar/webhooks.md` - Event handling
+- `references/polar/benefits.md` - Automated delivery
+- `references/polar/sdk.md` - Multi-language SDKs
+- `references/polar/best-practices.md` - Production patterns
+
+### Stripe
+- `references/stripe/stripe-best-practices.md` - Integration design
+- `references/stripe/stripe-sdks.md` - Server SDKs
+- `references/stripe/stripe-js.md` - Payment Element
+- `references/stripe/stripe-cli.md` - Local testing
+- `references/stripe/stripe-upgrade.md` - Version upgrades
+- External: https://docs.stripe.com/llms.txt
+
+### Paddle
+- `references/paddle/overview.md` - MoR, auth, entity IDs
+- `references/paddle/api.md` - Products, prices, transactions
+- `references/paddle/paddle-js.md` - Checkout overlay/inline
+- `references/paddle/subscriptions.md` - Trials, upgrades, pause
+- `references/paddle/webhooks.md` - SHA256 verification
+- `references/paddle/sdk.md` - Node, Python, PHP, Go
+- `references/paddle/best-practices.md` - Production patterns
+- External: https://developer.paddle.com/llms.txt
+
+### Creem.io
+- `references/creem/overview.md` - MoR, auth, global support
+- `references/creem/api.md` - Products, checkout sessions
+- `references/creem/checkouts.md` - No-code links, storefronts
+- `references/creem/subscriptions.md` - Trials, seat-based
+- `references/creem/licensing.md` - Device activation
+- `references/creem/webhooks.md` - Signature verification
+- `references/creem/sdk.md` - Next.js, Better Auth
+- External: https://docs.creem.io/llms.txt
+
+### Multi-Provider
+- `references/multi-provider-order-management-patterns.md` - Unified orders, currency conversion
+
+### Scripts
+- `scripts/sepay-webhook-verify.js` - SePay webhook verification
+- `scripts/polar-webhook-verify.js` - Polar webhook verification
+- `scripts/checkout-helper.js` - Checkout session generator
+
+## Key Capabilities
+
+| Platform | Highlights |
+|----------|------------|
+| **SePay** | QR/bank/cards, 44+ VN banks, webhooks, 2 req/s |
+| **Polar** | MoR, subscriptions, usage billing, benefits, 300 req/min |
+| **Stripe** | CheckoutSessions, Billing, Connect, Payment Element |
+| **Paddle** | MoR, overlay/inline checkout, Retain (churn prevention), tax |
+| **Creem.io** | MoR, licensing, revenue splits, no-code checkout |
+
+## Implementation
+
+See `references/implementation-workflows.md` for step-by-step guides per platform.
+
+**General flow:** auth → products → checkout → webhooks → events

package/.claude/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/.claude/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.

package/.claude/skills/payment-integration/references/creem/licensing.md

@@ -0,0 +1,136 @@
+# Creem.io Licensing
+
+Software licensing with device activation management.
+
+## License Flow
+
+```
+purchase → license_key issued → activate device → validate → deactivate
+```
+
+## Activate License
+
+Register a device against a license key:
+
+```javascript
+// POST /v1/licenses/activate
+const activation = await creem.licenses.activate({
+  license_key: 'XXXX-XXXX-XXXX-XXXX',
+  instance_id: 'device_fingerprint_123',  // Unique device identifier
+  instance_name: 'MacBook Pro'            // Optional friendly name
+});
+
+// Returns: {
+//   id: 'act_xxx',
+//   license_key: '...',
+//   instance_id: '...',
+//   activated_at: '...',
+//   valid_until: '...'
+// }
+```
+
+## Validate License
+
+Check if license is active for specific device:
+
+```javascript
+// POST /v1/licenses/validate
+const validation = await creem.licenses.validate({
+  license_key: 'XXXX-XXXX-XXXX-XXXX',
+  instance_id: 'device_fingerprint_123'
+});
+
+// Returns: {
+//   valid: true,
+//   license_key: '...',
+//   product_id: 'prod_xxx',
+//   customer_id: 'cus_xxx',
+//   expires_at: '2025-01-15T00:00:00Z',
+//   activations_used: 2,
+//   activations_limit: 5
+// }
+```
+
+## Deactivate License
+
+Remove device activation to free slot:
+
+```javascript
+// POST /v1/licenses/deactivate
+await creem.licenses.deactivate({
+  license_key: 'XXXX-XXXX-XXXX-XXXX',
+  instance_id: 'device_fingerprint_123'
+});
+```
+
+## Client-Side Implementation
+
+```javascript
+// Desktop app example (Electron, Tauri, etc.)
+class LicenseManager {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+    this.instanceId = this.getDeviceFingerprint();
+  }
+
+  getDeviceFingerprint() {
+    // Generate unique device ID (machine ID, hardware hash, etc.)
+    return require('node-machine-id').machineIdSync();
+  }
+
+  async activate(licenseKey) {
+    const response = await fetch('https://api.creem.io/v1/licenses/activate', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        license_key: licenseKey,
+        instance_id: this.instanceId,
+        instance_name: os.hostname()
+      })
+    });
+    return response.json();
+  }
+
+  async validate(licenseKey) {
+    const response = await fetch('https://api.creem.io/v1/licenses/validate', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        license_key: licenseKey,
+        instance_id: this.instanceId
+      })
+    });
+    const data = await response.json();
+    return data.valid;
+  }
+}
+```
+
+## Activation Limits
+
+Configure per product - limits simultaneous device activations:
+
+```javascript
+const product = await creem.products.create({
+  name: 'Desktop App License',
+  price: 4900,
+  currency: 'usd',
+  license_config: {
+    activations_limit: 3  // Max 3 devices per license
+  }
+});
+```
+
+## License Events (Webhooks)
+
+- `license.activated` - Device activated
+- `license.deactivated` - Device deactivated
+- `license.expired` - License expired (subscription ended)
+
+See `references/creem/webhooks.md` for webhook handling.