anchi-toolkit 1.2.0 → 1.2.2

package/dist/skills/payment-integration/references/sepay/sdk.md

@@ -0,0 +1,213 @@
+# SePay SDK Integration
+
+Official SDKs for Node.js, PHP, and Laravel.
+
+## Node.js SDK (sepay-pg-node)
+
+**Installation:**
+```bash
+npm install github:sepay/sepay-pg-node
+```
+
+**Requirements:** Node.js 16+
+
+**Configuration:**
+```javascript
+import { SePayPgClient } from 'sepay-pg-node';
+
+const client = new SePayPgClient({
+  env: 'sandbox',  // or 'production'
+  merchant_id: 'SP-TEST-XXXXXXX',
+  secret_key: 'spsk_test_xxxxxxxxxxxxx',
+});
+```
+
+**Create Payment:**
+```javascript
+const fields = client.checkout.initOneTimePaymentFields({
+  operation: 'PURCHASE',
+  order_invoice_number: 'DH0001',
+  order_amount: 10000,
+  currency: 'VND',
+  success_url: 'https://example.com/success',
+  error_url: 'https://example.com/error',
+  cancel_url: 'https://example.com/cancel',
+  order_description: 'Payment for order DH0001',
+});
+```
+
+**Render Payment Form:**
+```jsx
+<form action={client.checkout.initCheckoutUrl()} method="POST">
+  {Object.keys(fields).map(field =>
+    <input type="hidden" name={field} value={fields[field]} key={field} />
+  )}
+  <button type="submit">Pay Now</button>
+</form>
+```
+
+**API Methods:**
+```javascript
+// List all orders
+await client.order.all({
+  per_page: 50,
+  q: 'search_term',
+  order_status: 'completed',
+  from_created_at: '2025-01-01',
+  to_created_at: '2025-01-31'
+});
+
+// Get order details
+await client.order.retrieve('DH0001');
+
+// Void transaction (cards only)
+await client.order.voidTransaction('DH0001');
+
+// Cancel order (QR payments)
+await client.order.cancel('DH0001');
+```
+
+**Endpoints:**
+- Sandbox: `https://sandbox.pay.sepay.vn/v1/init`
+- Production: `https://pay.sepay.vn/v1/init`
+
+## PHP SDK (sepay/sepay-pg)
+
+**Installation:**
+```bash
+composer require sepay/sepay-pg
+```
+
+**Requirements:** PHP 7.4+, ext-json, ext-curl, Guzzle
+
+**Quick Start:**
+```php
+use SePay\SePayClient;
+use SePay\Builders\CheckoutBuilder;
+
+$sepay = new SePayClient(
+    'SP-TEST-XXXXXXX',
+    'spsk_live_xxxxxxxxxxxxx',
+    SePayClient::ENVIRONMENT_SANDBOX
+);
+
+$checkoutData = CheckoutBuilder::make()
+    ->currency('VND')
+    ->orderAmount(100000)
+    ->operation('PURCHASE')
+    ->orderDescription('Test payment')
+    ->orderInvoiceNumber('INV_001')
+    ->successUrl('https://yoursite.com/success')
+    ->errorUrl('https://yoursite.com/error')
+    ->cancelUrl('https://yoursite.com/cancel')
+    ->build();
+
+echo $sepay->checkout()->generateFormHtml($checkoutData);
+```
+
+**Error Handling:**
+```php
+try {
+    $order = $sepay->orders()->retrieve('INV_001');
+} catch (AuthenticationException $e) {
+    // Invalid credentials
+} catch (ValidationException $e) {
+    // Invalid request data
+    $errors = $e->getErrors();
+} catch (NotFoundException $e) {
+    // Resource not found
+} catch (RateLimitException $e) {
+    // Rate limit exceeded
+    $retryAfter = $e->getRetryAfter();
+} catch (ServerException $e) {
+    // Server error (5xx)
+}
+```
+
+**Configuration:**
+```php
+$sepay->setConfig([
+    'timeout' => 30,
+    'retry_attempts' => 3,
+    'retry_delay' => 1000,
+    'debug' => true,
+    'user_agent' => 'MyApp/1.0',
+    'logger' => $psrLogger
+]);
+```
+
+## Laravel Package (laravel-sepay)
+
+**Installation:**
+```bash
+composer require sepayvn/laravel-sepay
+
+# For Laravel 7-8 with PHP 7.4+
+composer require "sepayvn/laravel-sepay:dev-lite"
+```
+
+**Setup:**
+```bash
+php artisan vendor:publish --tag="sepay-migrations"
+php artisan migrate
+php artisan vendor:publish --tag="sepay-config"
+php artisan vendor:publish --tag="sepay-views"  # optional
+```
+
+**Configuration (.env):**
+```
+SEPAY_WEBHOOK_TOKEN=your_secret_key
+SEPAY_MATCH_PATTERN=SE
+```
+
+**Create Event Listener:**
+```bash
+php artisan make:listener SePayWebhookListener
+```
+
+**Listener Implementation:**
+```php
+<?php
+
+namespace App\Listeners;
+
+use SePayWebhookEvent;
+
+class SePayWebhookListener
+{
+    public function handle(SePayWebhookEvent $event)
+    {
+        $transaction = $event->transaction;
+
+        if ($transaction->transfer_type === 'in') {
+            // Handle incoming payment
+            Order::where('code', $transaction->content)
+                ->update(['status' => 'paid']);
+
+            // Send confirmation email
+            Mail::to($order->customer->email)
+                ->send(new PaymentConfirmation($order));
+        }
+    }
+}
+```
+
+**Register Listener:**
+```php
+// app/Providers/EventServiceProvider.php
+protected $listen = [
+    SePayWebhookEvent::class => [
+        SePayWebhookListener::class,
+    ],
+];
+```
+
+## Best Practices
+
+1. **Environment Variables:** Store credentials securely
+2. **Error Handling:** Catch and log all exceptions
+3. **Retry Logic:** Implement for transient failures
+4. **Logging:** Log all API calls and responses
+5. **Testing:** Use sandbox extensively before production
+6. **Validation:** Validate data before API calls
+7. **Monitoring:** Track success/failure rates

package/dist/skills/payment-integration/references/sepay/webhooks.md

@@ -0,0 +1,208 @@
+# SePay Webhooks
+
+Real-time payment notifications from SePay to your server.
+
+## Setup
+
+1. Access WebHooks menu in dashboard
+2. Click "+ Add webhooks"
+3. Configure:
+   - **Name:** Descriptive identifier
+   - **Event Selection:** `All`, `In_only`, `Out_only`
+   - **Conditions:** Bank accounts, VA filtering, payment code requirements
+   - **Webhook URL:** Your callback endpoint (must be publicly accessible)
+   - **Is Verify Payment:** Flag for validation
+   - **Authentication:** `No_Authen`, `OAuth2.0`, or `Api_Key`
+4. Click "Add" to finalize
+
+## Payload Structure
+
+```json
+{
+  "id": 92704,
+  "gateway": "Vietcombank",
+  "transactionDate": "2023-03-25 14:02:37",
+  "accountNumber": "0123499999",
+  "code": null,
+  "content": "payment content",
+  "transferType": "in",
+  "transferAmount": 2277000,
+  "accumulated": 19077000,
+  "subAccount": null,
+  "referenceCode": "MBVCB.3278907687"
+}
+```
+
+**Fields:**
+- `id` - Unique transaction ID (use for deduplication)
+- `gateway` - Bank name
+- `transactionDate` - Transaction timestamp
+- `accountNumber` - Bank account number
+- `code` - Payment code (if available)
+- `content` - Transfer description/content
+- `transferType` - "in" (incoming) or "out" (outgoing)
+- `transferAmount` - Transaction amount
+- `accumulated` - Account balance after transaction
+- `subAccount` - Sub-account identifier
+- `referenceCode` - Bank transaction reference
+
+## Authentication
+
+**API Key:**
+```
+Authorization: Apikey YOUR_KEY
+Content-Type: application/json
+```
+
+**OAuth 2.0:**
+Provide token endpoint, client ID, and client secret in dashboard.
+
+**No Authentication:**
+Available but not recommended for production. Consider IP whitelisting.
+
+## Response Requirements
+
+**Success Response:**
+```json
+HTTP/1.1 200 OK
+{
+  "success": true
+}
+```
+
+**Accepted:** Any 2xx status code (200-201)
+**Timeout:** Respond within 5 seconds
+
+## Auto-Retry Mechanism
+
+**Policy:**
+- Retries up to 7 times over ~5 hours
+- Fibonacci sequence intervals (1, 1, 2, 3, 5, 8, 13... minutes)
+
+**Duplicate Prevention:**
+```javascript
+// Primary: Use transaction ID
+const exists = await db.transactions.findOne({ sepay_id: data.id });
+if (exists) return { success: true };
+
+// Alternative: Composite key
+const key = `${data.referenceCode}-${data.transferType}-${data.transferAmount}`;
+```
+
+## Implementation Examples
+
+### Node.js/Express
+```javascript
+app.post('/webhook/sepay', async (req, res) => {
+  const transaction = req.body;
+
+  // Check duplicates
+  if (await isDuplicate(transaction.id)) {
+    return res.json({ success: true });
+  }
+
+  // Process transaction
+  if (transaction.transferType === 'in') {
+    await processPayment({
+      amount: transaction.transferAmount,
+      content: transaction.content,
+      referenceCode: transaction.referenceCode
+    });
+  }
+
+  // Save to database
+  await db.transactions.insert(transaction);
+
+  res.json({ success: true });
+});
+```
+
+### PHP
+```php
+<?php
+$data = json_decode(file_get_contents('php://input'), true);
+
+// Check duplicates
+$exists = $db->query("SELECT id FROM transactions WHERE sepay_id = ?", [$data['id']]);
+if ($exists) {
+    echo json_encode(['success' => true]);
+    exit;
+}
+
+// Process payment
+if ($data['transferType'] == 'in') {
+    processPayment($data['transferAmount'], $data['content']);
+}
+
+// Save to database
+$db->insert('transactions', [
+    'sepay_id' => $data['id'],
+    'amount' => $data['transferAmount'],
+    'content' => $data['content'],
+    'reference_code' => $data['referenceCode']
+]);
+
+header('Content-Type: application/json');
+echo json_encode(['success' => true]);
+```
+
+## Security Best Practices
+
+1. **IP Whitelisting:** Restrict endpoint to SePay IPs
+2. **API Key Verification:** Validate authorization header
+3. **HTTPS Only:** Use SSL/TLS
+4. **Duplicate Detection:** Prevent double processing
+5. **Logging:** Maintain webhook logs
+6. **Timeout Handling:** Respond quickly (<5s)
+7. **Idempotency:** Same webhook multiple times = same result
+
+## Monitoring
+
+**Dashboard Features:**
+- View webhook attempts
+- Check response status
+- Review retry history
+- Manual retry option
+
+**Application Monitoring:**
+- Log all webhook receipts
+- Track processing time
+- Alert on failures
+- Monitor duplicate rate
+
+## OAuth2 Webhook Management API
+
+**Available Scopes:** `webhook:read`, `webhook:write`, `webhook:delete`
+
+**List Webhooks:**
+```
+GET /api/v1/webhooks
+```
+
+**Get Details:**
+```
+GET /api/v1/webhooks/{id}
+```
+
+**Create:**
+```
+POST /api/v1/webhooks
+{
+  "bank_account_id": 123,
+  "name": "My Webhook",
+  "event_type": "All",
+  "authen_type": "Api_Key",
+  "webhook_url": "https://example.com/webhook",
+  "is_verify_payment": true
+}
+```
+
+**Update:**
+```
+PATCH /api/v1/webhooks/{id}
+```
+
+**Delete:**
+```
+DELETE /api/v1/webhooks/{id}
+```

package/dist/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/dist/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"
+}