@lovehlmmm/primekit 1.0.0

package/skills/payment-integration/references/stripe/stripe-upgrade.md

@@ -0,0 +1,175 @@
+---
+name: upgrade-stripe
+description: Guide for upgrading Stripe API versions and SDKs
+---
+
+# Upgrading Stripe Versions
+
+This skill covers upgrading Stripe API versions, server-side SDKs, Stripe.js, and mobile SDKs.
+
+**Full Documentation**: https://stripe.com/llms.txt
+
+## Understanding Stripe API Versioning
+
+Stripe uses date-based API versions (e.g., `2025-12-15.clover`, `2025-08-27.basil`, `2024-12-18.acacia`). Your account's API version determines request/response behavior.
+
+### Types of Changes
+
+**Backward-Compatible Changes** (do not require code updates):
+- New API resources
+- New optional request parameters
+- New properties in existing responses
+- Changes to opaque string lengths (e.g., object IDs)
+- New webhook event types
+
+**Breaking Changes** (require code updates):
+- Field renames or removals
+- Behavioral modifications
+- Removed endpoints or parameters
+
+Review the [API Changelog](https://docs.stripe.com/changelog.md) for all changes between versions.
+
+## Server-Side SDK Versioning
+
+See [SDK Version Management](https://docs.stripe.com/sdks/set-version.md) for details.
+
+### Dynamically-Typed Languages (Ruby, Python, PHP, Node.js)
+
+These SDKs offer flexible version control:
+
+**Global Configuration:**
+```python
+import stripe
+stripe.api_version = '2025-12-15.clover'
+```
+
+```ruby
+Stripe.api_version = '2025-12-15.clover'
+```
+
+```javascript
+const stripe = require('stripe')('sk_test_xxx', {
+  apiVersion: '2025-12-15.clover'
+});
+```
+
+**Per-Request Override:**
+```python
+stripe.Customer.create(
+  email="customer@example.com",
+  stripe_version='2025-12-15.clover'
+)
+```
+
+### Strongly-Typed Languages (Java, Go, .NET)
+
+These use a fixed API version matching the SDK release date. Do not set a different API version for strongly-typed languages because response objects might not match the strong types in the SDK. Instead, update the SDK to target a new API version.
+
+### Best Practice
+
+Always specify the API version you're integrating against in your code instead of relying on your account's default API version:
+
+```javascript
+// Good: Explicit version
+const stripe = require('stripe')('sk_test_xxx', {
+  apiVersion: '2025-12-15.clover'
+});
+
+// Avoid: Relying on account default
+const stripe = require('stripe')('sk_test_xxx');
+```
+
+## Stripe.js Versioning
+
+See [Stripe.js Versioning](https://docs.stripe.com/sdks/stripejs-versioning.md) for details.
+
+Stripe.js uses an evergreen model with major releases (Acacia, Basil, Clover) on a biannual basis.
+
+### Loading Versioned Stripe.js
+
+**Via Script Tag:**
+```html
+<script src="https://js.stripe.com/clover/stripe.js"></script>
+```
+
+**Via npm:**
+```bash
+npm install @stripe/stripe-js
+```
+
+Major npm versions correspond to specific Stripe.js versions.
+
+### API Version Pairing
+
+Each Stripe.js version automatically pairs with its corresponding API version. For instance:
+- Clover Stripe.js uses `2025-12-15.clover` API
+- Acacia Stripe.js uses `2024-12-18.acacia` API
+
+You cannot override this association.
+
+### Migrating from v3
+
+1. Identify your current API version in code
+2. Review the changelog for relevant changes
+3. Consider gradually updating your API version before switching Stripe.js versions
+4. Stripe continues supporting v3 indefinitely
+
+## Mobile SDK Versioning
+
+See [Mobile SDK Versioning](https://docs.stripe.com/sdks/mobile-sdk-versioning.md) for details.
+
+### iOS and Android SDKs
+
+Both platforms follow **semantic versioning** (MAJOR.MINOR.PATCH):
+- **MAJOR**: Breaking API changes
+- **MINOR**: New functionality (backward-compatible)
+- **PATCH**: Bug fixes (backward-compatible)
+
+New features and fixes release only on the latest major version. Upgrade regularly to access improvements.
+
+### React Native SDK
+
+Uses a different model (0.x.y schema):
+- **Minor version changes** (x): Breaking changes AND new features
+- **Patch updates** (y): Critical bug fixes only
+
+### Backend Compatibility
+
+All mobile SDKs work with any Stripe API version you use on your backend unless documentation specifies otherwise.
+
+## Upgrade Checklist
+
+1. Review the [API Changelog](https://docs.stripe.com/changelog.md) for changes between your current and target versions
+2. Check [Upgrades Guide](https://docs.stripe.com/upgrades.md) for migration guidance
+3. Update server-side SDK package version (e.g., `npm update stripe`, `pip install --upgrade stripe`)
+4. Update the `apiVersion` parameter in your Stripe client initialization
+5. Test your integration against the new API version using the `Stripe-Version` header
+6. Update webhook handlers to handle new event structures
+7. Update Stripe.js script tag or npm package version if needed
+8. Update mobile SDK versions in your package manager if needed
+9. Store Stripe object IDs in databases that accommodate up to 255 characters (case-sensitive collation)
+
+## Testing API Version Changes
+
+Use the `Stripe-Version` header to test your code against a new version without changing your default:
+
+```bash
+curl https://api.stripe.com/v1/customers \
+  -u sk_test_xxx: \
+  -H "Stripe-Version: 2025-12-15.clover"
+```
+
+Or in code:
+
+```javascript
+const stripe = require('stripe')('sk_test_xxx', {
+  apiVersion: '2025-12-15.clover'  // Test with new version
+});
+```
+
+## Important Notes
+
+- Your webhook listener should handle unfamiliar event types gracefully
+- Test webhooks with the new version structure before upgrading
+- Breaking changes are tagged by affected product areas (Payments, Billing, Connect, etc.)
+- Multiple API versions coexist simultaneously, enabling staged adoption

package/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/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/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/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;