@thanhvn14/csvibe 0.1.3 → 0.1.5

package/.github/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
+
+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 %USERPROFILE%/.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
+
+## 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/.github/skills/payment-integration/scripts/.env.example

@@ -0,0 +1,20 @@
+# SePay Configuration
+SEPAY_MERCHANT_ID=SP-TEST-XXXXXXX
+SEPAY_SECRET_KEY=spsk_test_xxxxxxxxxxxxx
+SEPAY_ENV=sandbox  # or 'production'
+
+# SePay Webhook Configuration
+SEPAY_WEBHOOK_AUTH_TYPE=api_key  # or 'oauth2' or 'none'
+SEPAY_WEBHOOK_API_KEY=your_webhook_api_key
+
+# Polar Configuration
+POLAR_ACCESS_TOKEN=polar_xxxxxxxxxxxxxxxx
+POLAR_SERVER=sandbox  # or 'production'
+POLAR_ORG_ID=org_xxxxxxxxxxxxx
+
+# Polar Webhook Configuration
+POLAR_WEBHOOK_SECRET=base64_encoded_secret
+
+# Optional: Database or other configuration
+# DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+# REDIS_URL=redis://localhost:6379

package/.github/skills/payment-integration/scripts/checkout-helper.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+/**
+ * Checkout Helper Script
+ *
+ * Generate checkout sessions for both SePay and Polar platforms.
+ *
+ * Usage:
+ *   node checkout-helper.js <platform> <config-json>
+ *
+ * Platforms: sepay, polar
+ *
+ * Environment Variables:
+ *   SEPAY_MERCHANT_ID, SEPAY_SECRET_KEY, SEPAY_ENV
+ *   POLAR_ACCESS_TOKEN, POLAR_SERVER
+ */
+
+const crypto = require('crypto');
+
+class CheckoutHelper {
+  /**
+   * Generate SePay checkout form fields
+   */
+  static generateSePayCheckout(config) {
+    const {
+      merchantId,
+      secretKey,
+      orderInvoiceNumber,
+      orderAmount,
+      currency = 'VND',
+      successUrl,
+      errorUrl,
+      cancelUrl,
+      orderDescription,
+      operation = 'PURCHASE'
+    } = config;
+
+    // Validate required fields
+    const required = ['merchantId', 'secretKey', 'orderInvoiceNumber', 'orderAmount', 'successUrl', 'errorUrl', 'cancelUrl'];
+    for (const field of required) {
+      if (!config[field]) {
+        throw new Error(`Missing required field: ${field}`);
+      }
+    }
+
+    // Build fields
+    const fields = {
+      merchant_id: merchantId,
+      operation: operation,
+      order_invoice_number: orderInvoiceNumber,
+      order_amount: orderAmount,
+      currency: currency,
+      success_url: successUrl,
+      error_url: errorUrl,
+      cancel_url: cancelUrl,
+      order_description: orderDescription || `Order ${orderInvoiceNumber}`,
+      timestamp: new Date().toISOString()
+    };
+
+    // Generate HMAC SHA256 signature
+    const signatureData = Object.keys(fields)
+      .sort()
+      .map(key => `${key}=${fields[key]}`)
+      .join('&');
+
+    const signature = crypto
+      .createHmac('sha256', secretKey)
+      .update(signatureData)
+      .digest('hex');
+
+    fields.signature = signature;
+
+    return {
+      fields,
+      formUrl: config.env === 'production'
+        ? 'https://pay.sepay.vn/v1/init'
+        : 'https://sandbox.pay.sepay.vn/v1/init',
+      htmlForm: this.generateHTMLForm(fields, config.env === 'production'
+        ? 'https://pay.sepay.vn/v1/init'
+        : 'https://sandbox.pay.sepay.vn/v1/init')
+    };
+  }
+
+  /**
+   * Generate Polar checkout configuration
+   */
+  static generatePolarCheckout(config) {
+    const {
+      productPriceId,
+      successUrl,
+      externalCustomerId,
+      customerEmail,
+      customerName,
+      discountId,
+      metadata,
+      embedOrigin
+    } = config;
+
+    // Validate required fields
+    if (!productPriceId) {
+      throw new Error('Missing required field: productPriceId');
+    }
+    if (!successUrl) {
+      throw new Error('Missing required field: successUrl');
+    }
+
+    // Must be absolute URL
+    if (!successUrl.startsWith('http://') && !successUrl.startsWith('https://')) {
+      throw new Error('successUrl must be an absolute URL');
+    }
+
+    const checkoutConfig = {
+      product_price_id: productPriceId,
+      success_url: successUrl
+    };
+
+    // Add optional fields
+    if (externalCustomerId) checkoutConfig.external_customer_id = externalCustomerId;
+    if (customerEmail) checkoutConfig.customer_email = customerEmail;
+    if (customerName) checkoutConfig.customer_name = customerName;
+    if (discountId) checkoutConfig.discount_id = discountId;
+    if (metadata) checkoutConfig.metadata = metadata;
+    if (embedOrigin) checkoutConfig.embed_origin = embedOrigin;
+
+    return {
+      config: checkoutConfig,
+      apiEndpoint: config.server === 'sandbox'
+        ? 'https://sandbox-api.polar.sh/v1/checkouts'
+        : 'https://api.polar.sh/v1/checkouts',
+      curlCommand: this.generatePolarCurl(checkoutConfig, config.accessToken, config.server)
+    };
+  }
+
+  /**
+   * Generate HTML form for SePay
+   */
+  static generateHTMLForm(fields, actionUrl) {
+    const inputs = Object.keys(fields)
+      .map(key => `    <input type="hidden" name="${key}" value="${fields[key]}" />`)
+      .join('\n');
+
+    return `
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>SePay Payment</title>
+</head>
+<body>
+  <form id="payment-form" action="${actionUrl}" method="POST">
+${inputs}
+    <button type="submit">Pay Now</button>
+  </form>
+
+  <script>
+    // Auto-submit form
+    // document.getElementById('payment-form').submit();
+  </script>
+</body>
+</html>
+`.trim();
+  }
+
+  /**
+   * Generate cURL command for Polar
+   */
+  static generatePolarCurl(config, accessToken, server = 'production') {
+    const endpoint = server === 'sandbox'
+      ? 'https://sandbox-api.polar.sh/v1/checkouts'
+      : 'https://api.polar.sh/v1/checkouts';
+
+    return `curl -X POST ${endpoint} \\
+  -H "Authorization: Bearer ${accessToken}" \\
+  -H "Content-Type: application/json" \\
+  -d '${JSON.stringify(config, null, 2)}'`;
+  }
+}
+
+// CLI Usage
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    console.log('Usage: node checkout-helper.js <platform> <config-json>');
+    console.log('\nPlatforms:');
+    console.log('  sepay  - SePay checkout form generation');
+    console.log('  polar  - Polar checkout session configuration');
+    console.log('\nExamples:');
+    console.log('\nSePay:');
+    console.log('  node checkout-helper.js sepay \'{"orderInvoiceNumber":"ORD001","orderAmount":100000,"successUrl":"https://example.com/success","errorUrl":"https://example.com/error","cancelUrl":"https://example.com/cancel"}\'');
+    console.log('\nPolar:');
+    console.log('  node checkout-helper.js polar \'{"productPriceId":"price_xxx","successUrl":"https://example.com/success","externalCustomerId":"user_123"}\'');
+    process.exit(1);
+  }
+
+  try {
+    const platform = args[0].toLowerCase();
+    const config = JSON.parse(args[1]);
+
+    if (platform === 'sepay') {
+      // Get from environment or config
+      config.merchantId = config.merchantId || process.env.SEPAY_MERCHANT_ID;
+      config.secretKey = config.secretKey || process.env.SEPAY_SECRET_KEY;
+      config.env = config.env || process.env.SEPAY_ENV || 'sandbox';
+
+      const result = CheckoutHelper.generateSePayCheckout(config);
+
+      console.log('✓ SePay Checkout Generated\n');
+      console.log('Form URL:', result.formUrl);
+      console.log('\nForm Fields:');
+      console.log(JSON.stringify(result.fields, null, 2));
+      console.log('\nHTML Form:');
+      console.log(result.htmlForm);
+    } else if (platform === 'polar') {
+      // Get from environment or config
+      config.accessToken = config.accessToken || process.env.POLAR_ACCESS_TOKEN;
+      config.server = config.server || process.env.POLAR_SERVER || 'production';
+
+      if (!config.accessToken) {
+        console.error('✗ Error: POLAR_ACCESS_TOKEN is required');
+        console.error('Set it via environment variable or in config JSON');
+        process.exit(1);
+      }
+
+      const result = CheckoutHelper.generatePolarCheckout(config);
+
+      console.log('✓ Polar Checkout Configuration Generated\n');
+      console.log('API Endpoint:', result.apiEndpoint);
+      console.log('\nCheckout Configuration:');
+      console.log(JSON.stringify(result.config, null, 2));
+      console.log('\ncURL Command:');
+      console.log(result.curlCommand);
+    } else {
+      console.error(`✗ Error: Unknown platform '${platform}'`);
+      console.error('Supported platforms: sepay, polar');
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('✗ Error:', error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = CheckoutHelper;

package/.github/skills/payment-integration/scripts/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "payment-integration-scripts",
+  "version": "1.0.0",
+  "description": "Helper scripts for SePay and Polar payment integration",
+  "scripts": {
+    "test": "node test-scripts.js"
+  },
+  "keywords": [
+    "payment",
+    "sepay",
+    "polar",
+    "webhook",
+    "checkout"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/.github/skills/payment-integration/scripts/polar-webhook-verify.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+/**
+ * Polar Webhook Verification Script
+ *
+ * Verifies Polar webhook signatures following Standard Webhooks specification.
+ *
+ * Usage:
+ *   node polar-webhook-verify.js <webhook-payload-json> <webhook-secret>
+ *
+ * Environment Variables:
+ *   POLAR_WEBHOOK_SECRET - Webhook secret (base64 encoded)
+ */
+
+const crypto = require('crypto');
+
+class PolarWebhookVerifier {
+  constructor(secret) {
+    if (!secret) {
+      throw new Error('Webhook secret is required');
+    }
+    // Decode base64 secret
+    this.secret = Buffer.from(secret, 'base64');
+  }
+
+  /**
+   * Verify webhook signature
+   */
+  verifySignature(payload, headers) {
+    const webhookId = headers['webhook-id'];
+    const webhookTimestamp = headers['webhook-timestamp'];
+    const webhookSignature = headers['webhook-signature'];
+
+    if (!webhookId || !webhookTimestamp || !webhookSignature) {
+      throw new Error('Missing required webhook headers');
+    }
+
+    // Check timestamp (reject if > 5 minutes old)
+    const timestamp = parseInt(webhookTimestamp);
+    const now = Math.floor(Date.now() / 1000);
+
+    if (Math.abs(now - timestamp) > 300) {
+      throw new Error('Webhook timestamp too old or in future');
+    }
+
+    // Parse signatures
+    const signatures = webhookSignature.split(',').map(sig => {
+      const parts = sig.split('=');
+      const version = parts[0];
+      const signature = parts.slice(1).join('='); // Rejoin in case signature contains '='
+      return { version, signature };
+    });
+
+    // Create signed payload
+    const signedPayload = `${webhookTimestamp}.${payload}`;
+
+    // Compute expected signature
+    const expectedSignature = crypto
+      .createHmac('sha256', this.secret)
+      .update(signedPayload)
+      .digest('base64');
+
+    // Check if any signature matches
+    const isValid = signatures.some(sig => {
+      return sig.version === 'v1' && sig.signature === expectedSignature;
+    });
+
+    if (!isValid) {
+      throw new Error('Invalid webhook signature');
+    }
+
+    return true;
+  }
+
+  /**
+   * Process webhook event
+   */
+  process(payload, headers) {
+    try {
+      // Verify signature
+      this.verifySignature(payload, headers);
+
+      // Parse payload
+      const event = typeof payload === 'string' ? JSON.parse(payload) : payload;
+
+      // Validate event structure
+      if (!event.type || !event.data) {
+        throw new Error('Invalid event structure');
+      }
+
+      return {
+        success: true,
+        event: {
+          type: event.type,
+          data: event.data
+        }
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * Get event category
+   */
+  static getEventCategory(eventType) {
+    const categories = {
+      'checkout.': 'checkout',
+      'order.': 'order',
+      'subscription.': 'subscription',
+      'customer.': 'customer',
+      'benefit_grant.': 'benefit',
+      'refund.': 'refund',
+      'product.': 'product'
+    };
+
+    for (const [prefix, category] of Object.entries(categories)) {
+      if (eventType.startsWith(prefix)) {
+        return category;
+      }
+    }
+
+    return 'unknown';
+  }
+
+  /**
+   * Check if event is a payment
+   */
+  static isPaymentEvent(eventType) {
+    return ['order.paid', 'order.created'].includes(eventType);
+  }
+
+  /**
+   * Check if event is a subscription change
+   */
+  static isSubscriptionEvent(eventType) {
+    return eventType.startsWith('subscription.');
+  }
+}
+
+// CLI Usage
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 1) {
+    console.log('Usage: node polar-webhook-verify.js <webhook-payload-json> [webhook-secret]');
+    console.log('\nWebhook secret can also be provided via POLAR_WEBHOOK_SECRET environment variable');
+    console.log('\nExample:');
+    console.log('  node polar-webhook-verify.js \'{"type":"order.paid","data":{...}}\' base64secret');
+    process.exit(1);
+  }
+
+  try {
+    const payload = args[0];
+    const secret = args[1] || process.env.POLAR_WEBHOOK_SECRET;
+
+    if (!secret) {
+      console.error('✗ Error: Webhook secret is required');
+      console.error('Provide it as second argument or set POLAR_WEBHOOK_SECRET environment variable');
+      process.exit(1);
+    }
+
+    // Mock headers for CLI testing
+    const timestamp = Math.floor(Date.now() / 1000);
+    const signedPayload = `${timestamp}.${payload}`;
+    const signature = crypto
+      .createHmac('sha256', Buffer.from(secret, 'base64'))
+      .update(signedPayload)
+      .digest('base64');
+
+    const headers = {
+      'webhook-id': 'msg_test_' + Date.now(),
+      'webhook-timestamp': timestamp.toString(),
+      'webhook-signature': `v1=${signature}`
+    };
+
+    const verifier = new PolarWebhookVerifier(secret);
+    const result = verifier.process(payload, headers);
+
+    if (result.success) {
+      console.log('✓ Webhook verified successfully\n');
+      console.log('Event Details:');
+      console.log(`  Type: ${result.event.type}`);
+      console.log(`  Category: ${PolarWebhookVerifier.getEventCategory(result.event.type)}`);
+      console.log(`  Is Payment: ${PolarWebhookVerifier.isPaymentEvent(result.event.type) ? 'Yes' : 'No'}`);
+      console.log(`  Is Subscription: ${PolarWebhookVerifier.isSubscriptionEvent(result.event.type) ? 'Yes' : 'No'}`);
+      console.log('\nEvent Data:');
+      console.log(JSON.stringify(result.event.data, null, 2));
+    } else {
+      console.error('✗ Verification failed:', result.error);
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('✗ Error:', error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = PolarWebhookVerifier;