@ngxtm/devkit 3.0.2 → 3.1.0

package/skills/payment-integration/SKILL.md

@@ -1,118 +1,77 @@
 ---
 name: payment-integration
-description: Integrate payments with SePay (VietQR, Vietnamese bank transfers) and Polar (global SaaS subscriptions, billing). Use for checkout flows, webhooks, QR codes, subscription management.
-version: 1.0.0
-license: MIT
+description: Integrate Stripe, PayPal, and payment processors. Handles checkout
+  flows, subscriptions, webhooks, and PCI compliance. Use PROACTIVELY when
+  implementing payments, billing, or subscription features.
+metadata:
+  model: sonnet
 ---
 
-# 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
+## Use this skill when
 
-## Instructions
+- Working on payment integration tasks or workflows
+- Needing guidance, best practices, or checklists for payment integration
+
+## Do not use this skill when
 
-When implementing payment integration:
+- The task is unrelated to payment integration
+- You need a different domain or tool outside this scope
 
-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
+## Instructions
 
-Load only the references needed for current implementation step to maintain context efficiency.
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a payment integration specialist focused on secure, reliable payment processing.
+
+## Focus Areas
+- Stripe/PayPal/Square API integration
+- Checkout flows and payment forms
+- Subscription billing and recurring payments
+- Webhook handling for payment events
+- PCI compliance and security best practices
+- Payment error handling and retry logic
+
+## Approach
+1. Security first - never log sensitive card data
+2. Implement idempotency for all payment operations
+3. Handle all edge cases (failed payments, disputes, refunds)
+4. Test mode first, with clear migration path to production
+5. Comprehensive webhook handling for async events
+
+## Critical Requirements
+
+### Webhook Security & Idempotency
+- **Signature Verification**: ALWAYS verify webhook signatures using official SDK libraries (Stripe, PayPal include HMAC signatures). Never process unverified webhooks.
+- **Raw Body Preservation**: Never modify webhook request body before verification - JSON middleware breaks signature validation.
+- **Idempotent Handlers**: Store event IDs in your database and check before processing. Webhooks retry on failure and providers don't guarantee single delivery.
+- **Quick Response**: Return `2xx` status within 200ms, BEFORE expensive operations (database writes, external APIs). Timeouts trigger retries and duplicate processing.
+- **Server Validation**: Re-fetch payment status from provider API. Never trust webhook payload or client response alone.
+
+### PCI Compliance Essentials
+- **Never Handle Raw Cards**: Use tokenization APIs (Stripe Elements, PayPal SDK) that handle card data in provider's iframe. NEVER store, process, or transmit raw card numbers.
+- **Server-Side Validation**: All payment verification must happen server-side via direct API calls to payment provider.
+- **Environment Separation**: Test credentials must fail in production. Misconfigured gateways commonly accept test cards on live sites.
+
+## Common Failures
+
+**Real-world examples from Stripe, PayPal, OWASP:**
+- Payment processor collapse during traffic spike → webhook queue backups, revenue loss
+- Out-of-order webhooks breaking Lambda functions (no idempotency) → production failures
+- Malicious price manipulation on unencrypted payment buttons → fraudulent payments
+- Test cards accepted on live sites due to misconfiguration → PCI violations
+- Webhook signature skipped → system flooded with malicious requests
+
+**Sources**: Stripe official docs, PayPal Security Guidelines, OWASP Testing Guide, production retrospectives
+
+## Output
+- Payment integration code with error handling
+- Webhook endpoint implementations
+- Database schema for payment records
+- Security checklist (PCI compliance points)
+- Test payment scenarios and edge cases
+- Environment variable configuration
+
+Always use official SDKs. Include both server-side and client-side code where needed.

package/skills/paypal-integration/SKILL.md

@@ -0,0 +1,479 @@
+---
+name: paypal-integration
+description: Integrate PayPal payment processing with support for express checkout, subscriptions, and refund management. Use when implementing PayPal payments, processing online transactions, or building e-commerce checkout flows.
+---
+
+# PayPal Integration
+
+Master PayPal payment integration including Express Checkout, IPN handling, recurring billing, and refund workflows.
+
+## Do not use this skill when
+
+- The task is unrelated to paypal integration
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Use this skill when
+
+- Integrating PayPal as a payment option
+- Implementing express checkout flows
+- Setting up recurring billing with PayPal
+- Processing refunds and payment disputes
+- Handling PayPal webhooks (IPN)
+- Supporting international payments
+- Implementing PayPal subscriptions
+
+## Core Concepts
+
+### 1. Payment Products
+**PayPal Checkout**
+- One-time payments
+- Express checkout experience
+- Guest and PayPal account payments
+
+**PayPal Subscriptions**
+- Recurring billing
+- Subscription plans
+- Automatic renewals
+
+**PayPal Payouts**
+- Send money to multiple recipients
+- Marketplace and platform payments
+
+### 2. Integration Methods
+**Client-Side (JavaScript SDK)**
+- Smart Payment Buttons
+- Hosted payment flow
+- Minimal backend code
+
+**Server-Side (REST API)**
+- Full control over payment flow
+- Custom checkout UI
+- Advanced features
+
+### 3. IPN (Instant Payment Notification)
+- Webhook-like payment notifications
+- Asynchronous payment updates
+- Verification required
+
+## Quick Start
+
+```javascript
+// Frontend - PayPal Smart Buttons
+<div id="paypal-button-container"></div>
+
+<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD"></script>
+<script>
+  paypal.Buttons({
+    createOrder: function(data, actions) {
+      return actions.order.create({
+        purchase_units: [{
+          amount: {
+            value: '25.00'
+          }
+        }]
+      });
+    },
+    onApprove: function(data, actions) {
+      return actions.order.capture().then(function(details) {
+        // Payment successful
+        console.log('Transaction completed by ' + details.payer.name.given_name);
+
+        // Send to backend for verification
+        fetch('/api/paypal/capture', {
+          method: 'POST',
+          headers: {'Content-Type': 'application/json'},
+          body: JSON.stringify({orderID: data.orderID})
+        });
+      });
+    }
+  }).render('#paypal-button-container');
+</script>
+```
+
+```python
+# Backend - Verify and capture order
+from paypalrestsdk import Payment
+import paypalrestsdk
+
+paypalrestsdk.configure({
+    "mode": "sandbox",  # or "live"
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET"
+})
+
+def capture_paypal_order(order_id):
+    """Capture a PayPal order."""
+    payment = Payment.find(order_id)
+
+    if payment.execute({"payer_id": payment.payer.payer_info.payer_id}):
+        # Payment successful
+        return {
+            'status': 'success',
+            'transaction_id': payment.id,
+            'amount': payment.transactions[0].amount.total
+        }
+    else:
+        # Payment failed
+        return {
+            'status': 'failed',
+            'error': payment.error
+        }
+```
+
+## Express Checkout Implementation
+
+### Server-Side Order Creation
+```python
+import requests
+import json
+
+class PayPalClient:
+    def __init__(self, client_id, client_secret, mode='sandbox'):
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.base_url = 'https://api-m.sandbox.paypal.com' if mode == 'sandbox' else 'https://api-m.paypal.com'
+        self.access_token = self.get_access_token()
+
+    def get_access_token(self):
+        """Get OAuth access token."""
+        url = f"{self.base_url}/v1/oauth2/token"
+        headers = {"Accept": "application/json", "Accept-Language": "en_US"}
+
+        response = requests.post(
+            url,
+            headers=headers,
+            data={"grant_type": "client_credentials"},
+            auth=(self.client_id, self.client_secret)
+        )
+
+        return response.json()['access_token']
+
+    def create_order(self, amount, currency='USD'):
+        """Create a PayPal order."""
+        url = f"{self.base_url}/v2/checkout/orders"
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.access_token}"
+        }
+
+        payload = {
+            "intent": "CAPTURE",
+            "purchase_units": [{
+                "amount": {
+                    "currency_code": currency,
+                    "value": str(amount)
+                }
+            }]
+        }
+
+        response = requests.post(url, headers=headers, json=payload)
+        return response.json()
+
+    def capture_order(self, order_id):
+        """Capture payment for an order."""
+        url = f"{self.base_url}/v2/checkout/orders/{order_id}/capture"
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.access_token}"
+        }
+
+        response = requests.post(url, headers=headers)
+        return response.json()
+
+    def get_order_details(self, order_id):
+        """Get order details."""
+        url = f"{self.base_url}/v2/checkout/orders/{order_id}"
+        headers = {
+            "Authorization": f"Bearer {self.access_token}"
+        }
+
+        response = requests.get(url, headers=headers)
+        return response.json()
+```
+
+## IPN (Instant Payment Notification) Handling
+
+### IPN Verification and Processing
+```python
+from flask import Flask, request
+import requests
+from urllib.parse import parse_qs
+
+app = Flask(__name__)
+
+@app.route('/ipn', methods=['POST'])
+def handle_ipn():
+    """Handle PayPal IPN notifications."""
+    # Get IPN message
+    ipn_data = request.form.to_dict()
+
+    # Verify IPN with PayPal
+    if not verify_ipn(ipn_data):
+        return 'IPN verification failed', 400
+
+    # Process IPN based on transaction type
+    payment_status = ipn_data.get('payment_status')
+    txn_type = ipn_data.get('txn_type')
+
+    if payment_status == 'Completed':
+        handle_payment_completed(ipn_data)
+    elif payment_status == 'Refunded':
+        handle_refund(ipn_data)
+    elif payment_status == 'Reversed':
+        handle_chargeback(ipn_data)
+
+    return 'IPN processed', 200
+
+def verify_ipn(ipn_data):
+    """Verify IPN message authenticity."""
+    # Add 'cmd' parameter
+    verify_data = ipn_data.copy()
+    verify_data['cmd'] = '_notify-validate'
+
+    # Send back to PayPal for verification
+    paypal_url = 'https://ipnpb.sandbox.paypal.com/cgi-bin/webscr'  # or production URL
+
+    response = requests.post(paypal_url, data=verify_data)
+
+    return response.text == 'VERIFIED'
+
+def handle_payment_completed(ipn_data):
+    """Process completed payment."""
+    txn_id = ipn_data.get('txn_id')
+    payer_email = ipn_data.get('payer_email')
+    mc_gross = ipn_data.get('mc_gross')
+    item_name = ipn_data.get('item_name')
+
+    # Check if already processed (prevent duplicates)
+    if is_transaction_processed(txn_id):
+        return
+
+    # Update database
+    # Send confirmation email
+    # Fulfill order
+    print(f"Payment completed: {txn_id}, Amount: ${mc_gross}")
+
+def handle_refund(ipn_data):
+    """Handle refund."""
+    parent_txn_id = ipn_data.get('parent_txn_id')
+    mc_gross = ipn_data.get('mc_gross')
+
+    # Process refund in your system
+    print(f"Refund processed: {parent_txn_id}, Amount: ${mc_gross}")
+
+def handle_chargeback(ipn_data):
+    """Handle payment reversal/chargeback."""
+    txn_id = ipn_data.get('txn_id')
+    reason_code = ipn_data.get('reason_code')
+
+    # Handle chargeback
+    print(f"Chargeback: {txn_id}, Reason: {reason_code}")
+```
+
+## Subscription/Recurring Billing
+
+### Create Subscription Plan
+```python
+def create_subscription_plan(name, amount, interval='MONTH'):
+    """Create a subscription plan."""
+    client = PayPalClient(CLIENT_ID, CLIENT_SECRET)
+
+    url = f"{client.base_url}/v1/billing/plans"
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {client.access_token}"
+    }
+
+    payload = {
+        "product_id": "PRODUCT_ID",  # Create product first
+        "name": name,
+        "billing_cycles": [{
+            "frequency": {
+                "interval_unit": interval,
+                "interval_count": 1
+            },
+            "tenure_type": "REGULAR",
+            "sequence": 1,
+            "total_cycles": 0,  # Infinite
+            "pricing_scheme": {
+                "fixed_price": {
+                    "value": str(amount),
+                    "currency_code": "USD"
+                }
+            }
+        }],
+        "payment_preferences": {
+            "auto_bill_outstanding": True,
+            "setup_fee": {
+                "value": "0",
+                "currency_code": "USD"
+            },
+            "setup_fee_failure_action": "CONTINUE",
+            "payment_failure_threshold": 3
+        }
+    }
+
+    response = requests.post(url, headers=headers, json=payload)
+    return response.json()
+
+def create_subscription(plan_id, subscriber_email):
+    """Create a subscription for a customer."""
+    client = PayPalClient(CLIENT_ID, CLIENT_SECRET)
+
+    url = f"{client.base_url}/v1/billing/subscriptions"
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {client.access_token}"
+    }
+
+    payload = {
+        "plan_id": plan_id,
+        "subscriber": {
+            "email_address": subscriber_email
+        },
+        "application_context": {
+            "return_url": "https://yourdomain.com/subscription/success",
+            "cancel_url": "https://yourdomain.com/subscription/cancel"
+        }
+    }
+
+    response = requests.post(url, headers=headers, json=payload)
+    subscription = response.json()
+
+    # Get approval URL
+    for link in subscription.get('links', []):
+        if link['rel'] == 'approve':
+            return {
+                'subscription_id': subscription['id'],
+                'approval_url': link['href']
+            }
+```
+
+## Refund Workflows
+
+```python
+def create_refund(capture_id, amount=None, note=None):
+    """Create a refund for a captured payment."""
+    client = PayPalClient(CLIENT_ID, CLIENT_SECRET)
+
+    url = f"{client.base_url}/v2/payments/captures/{capture_id}/refund"
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {client.access_token}"
+    }
+
+    payload = {}
+    if amount:
+        payload["amount"] = {
+            "value": str(amount),
+            "currency_code": "USD"
+        }
+
+    if note:
+        payload["note_to_payer"] = note
+
+    response = requests.post(url, headers=headers, json=payload)
+    return response.json()
+
+def get_refund_details(refund_id):
+    """Get refund details."""
+    client = PayPalClient(CLIENT_ID, CLIENT_SECRET)
+
+    url = f"{client.base_url}/v2/payments/refunds/{refund_id}"
+    headers = {
+        "Authorization": f"Bearer {client.access_token}"
+    }
+
+    response = requests.get(url, headers=headers)
+    return response.json()
+```
+
+## Error Handling
+
+```python
+class PayPalError(Exception):
+    """Custom PayPal error."""
+    pass
+
+def handle_paypal_api_call(api_function):
+    """Wrapper for PayPal API calls with error handling."""
+    try:
+        result = api_function()
+        return result
+    except requests.exceptions.RequestException as e:
+        # Network error
+        raise PayPalError(f"Network error: {str(e)}")
+    except Exception as e:
+        # Other errors
+        raise PayPalError(f"PayPal API error: {str(e)}")
+
+# Usage
+try:
+    order = handle_paypal_api_call(lambda: client.create_order(25.00))
+except PayPalError as e:
+    # Handle error appropriately
+    log_error(e)
+```
+
+## Testing
+
+```python
+# Use sandbox credentials
+SANDBOX_CLIENT_ID = "..."
+SANDBOX_SECRET = "..."
+
+# Test accounts
+# Create test buyer and seller accounts at developer.paypal.com
+
+def test_payment_flow():
+    """Test complete payment flow."""
+    client = PayPalClient(SANDBOX_CLIENT_ID, SANDBOX_SECRET, mode='sandbox')
+
+    # Create order
+    order = client.create_order(10.00)
+    assert 'id' in order
+
+    # Get approval URL
+    approval_url = next((link['href'] for link in order['links'] if link['rel'] == 'approve'), None)
+    assert approval_url is not None
+
+    # After approval (manual step with test account)
+    # Capture order
+    # captured = client.capture_order(order['id'])
+    # assert captured['status'] == 'COMPLETED'
+```
+
+## Resources
+
+- **references/express-checkout.md**: Express Checkout implementation guide
+- **references/ipn-handling.md**: IPN verification and processing
+- **references/refund-workflows.md**: Refund handling patterns
+- **references/billing-agreements.md**: Recurring billing setup
+- **assets/paypal-client.py**: Production PayPal client
+- **assets/ipn-processor.py**: IPN webhook processor
+- **assets/recurring-billing.py**: Subscription management
+
+## Best Practices
+
+1. **Always Verify IPN**: Never trust IPN without verification
+2. **Idempotent Processing**: Handle duplicate IPN notifications
+3. **Error Handling**: Implement robust error handling
+4. **Logging**: Log all transactions and errors
+5. **Test Thoroughly**: Use sandbox extensively
+6. **Webhook Backup**: Don't rely solely on client-side callbacks
+7. **Currency Handling**: Always specify currency explicitly
+
+## Common Pitfalls
+
+- **Not Verifying IPN**: Accepting IPN without verification
+- **Duplicate Processing**: Not checking for duplicate transactions
+- **Wrong Environment**: Mixing sandbox and production URLs/credentials
+- **Missing Webhooks**: Not handling all payment states
+- **Hardcoded Values**: Not making configurable for different environments