anchi-toolkit 1.0.0 → 1.2.1

package/dist/skills/payment-integration/references/sepay/best-practices.md

@@ -0,0 +1,337 @@
+# SePay Best Practices
+
+Security, patterns, and monitoring for production SePay integrations.
+
+## Security
+
+### Credential Management
+```javascript
+// ✓ Good: Environment variables
+const client = new SePayClient({
+  merchant_id: process.env.SEPAY_MERCHANT_ID,
+  secret_key: process.env.SEPAY_SECRET_KEY,
+  env: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox'
+});
+
+// ✗ Bad: Hardcoded credentials
+const client = new SePayClient({
+  merchant_id: 'SP-TEST-12345',
+  secret_key: 'spsk_test_xxxxxxx'
+});
+```
+
+### Webhook Security
+1. **IP Whitelisting:** Restrict endpoint to SePay IPs
+2. **API Key Verification:** Validate authorization header
+3. **HTTPS Only:** Never accept HTTP webhooks
+4. **Validate Payload:** Check all required fields exist
+5. **Duplicate Detection:** Use transaction ID for deduplication
+
+### Transaction Verification
+```javascript
+// Always verify payment status via API, don't trust only redirects
+app.get('/payment/success', async (req, res) => {
+  const orderId = req.query.order_id;
+
+  // Verify via API call
+  const order = await sePayClient.order.retrieve(orderId);
+
+  if (order.status === 'completed') {
+    await updateOrderStatus(orderId, 'paid');
+    res.redirect(`/order/${orderId}/confirmation`);
+  } else {
+    res.redirect(`/order/${orderId}/pending`);
+  }
+});
+```
+
+## Implementation Patterns
+
+### Payment Flow Pattern
+```javascript
+class PaymentService {
+  async createPayment(order) {
+    // 1. Create order in your system
+    const paymentCode = `ORDER_${order.id}_${Date.now()}`;
+    await this.savePaymentCode(order.id, paymentCode);
+
+    // 2. Generate checkout form
+    const fields = this.client.checkout.initOneTimePaymentFields({
+      order_invoice_number: paymentCode,
+      order_amount: order.total,
+      currency: 'VND',
+      success_url: `${config.baseUrl}/payment/success?order=${order.id}`,
+      error_url: `${config.baseUrl}/payment/error?order=${order.id}`,
+      cancel_url: `${config.baseUrl}/payment/cancel?order=${order.id}`,
+      order_description: `Payment for Order #${order.id}`,
+    });
+
+    return fields;
+  }
+
+  async verifyPayment(orderId) {
+    const paymentCode = await this.getPaymentCode(orderId);
+    const payment = await this.client.order.retrieve(paymentCode);
+
+    return {
+      isPaid: payment.status === 'completed',
+      amount: payment.amount,
+      paidAt: payment.completed_at,
+    };
+  }
+}
+```
+
+### Webhook Resilience Pattern
+```javascript
+async function handleWebhook(data) {
+  const maxRetries = 3;
+  let attempt = 0;
+
+  while (attempt < maxRetries) {
+    try {
+      await db.transaction(async (trx) => {
+        // Check duplicate
+        const exists = await trx('transactions')
+          .where('sepay_id', data.id)
+          .first();
+
+        if (exists) return;
+
+        // Save transaction
+        await trx('transactions').insert({
+          sepay_id: data.id,
+          amount: data.transferAmount,
+          content: data.content,
+          reference_code: data.referenceCode,
+        });
+
+        // Process payment
+        const order = await findOrderByPaymentCode(data.content);
+        if (order) {
+          await markOrderAsPaid(order.id, trx);
+        }
+      });
+
+      return { success: true };
+    } catch (error) {
+      attempt++;
+      if (attempt >= maxRetries) throw error;
+      await sleep(1000 * attempt); // Exponential backoff
+    }
+  }
+}
+```
+
+### Reconciliation Pattern
+```javascript
+async function reconcilePayments(fromDate, toDate) {
+  // Get all pending orders
+  const pendingOrders = await Order.findPending();
+
+  // Fetch SePay transactions in batches
+  let sinceId = 0;
+  const batchSize = 1000;
+
+  while (true) {
+    const transactions = await sePayClient.transaction.list({
+      transaction_date_min: fromDate,
+      transaction_date_max: toDate,
+      transfer_type: 'in',
+      since_id: sinceId,
+      limit: batchSize,
+    });
+
+    if (transactions.length === 0) break;
+
+    // Match and update
+    for (const transaction of transactions) {
+      const order = pendingOrders.find(o =>
+        transaction.content.includes(o.payment_code)
+      );
+
+      if (order) {
+        await order.markAsPaid(transaction);
+      }
+    }
+
+    sinceId = transactions[transactions.length - 1].id;
+  }
+}
+```
+
+## Performance Optimization
+
+### Caching
+```javascript
+// Cache bank list
+const getBankList = memoize(
+  async () => {
+    const response = await fetch('https://qr.sepay.vn/banks.json');
+    return response.json();
+  },
+  { maxAge: 86400000 } // 24 hours
+);
+
+// Cache QR codes for fixed amounts
+const qrCache = new Map();
+
+function getCachedQRUrl(account, bank, amount) {
+  const key = `${account}-${bank}-${amount}`;
+  if (!qrCache.has(key)) {
+    const url = generateQRUrl(account, bank, amount);
+    qrCache.set(key, url);
+  }
+  return qrCache.get(key);
+}
+```
+
+### Rate Limit Management
+```javascript
+const RateLimiter = require('bottleneck');
+
+const limiter = new RateLimiter({
+  maxConcurrent: 1,
+  minTime: 500, // 2 requests per second
+  reservoir: 100,
+  reservoirRefreshAmount: 100,
+  reservoirRefreshInterval: 60000, // per minute
+});
+
+// Wrap API calls
+const apiCall = limiter.wrap(async (endpoint, params) => {
+  return await sePayClient.api.call(endpoint, params);
+});
+```
+
+### Async Processing
+```javascript
+// Queue webhook processing
+app.post('/webhook/sepay', async (req, res) => {
+  // Respond immediately
+  res.json({ success: true });
+
+  // Queue for background processing
+  await webhookQueue.add('process-sepay-webhook', req.body, {
+    attempts: 3,
+    backoff: {
+      type: 'exponential',
+      delay: 2000,
+    },
+  });
+});
+
+// Process in background worker
+webhookQueue.process('process-sepay-webhook', async (job) => {
+  await handleWebhook(job.data);
+});
+```
+
+## Monitoring & Logging
+
+### Essential Metrics
+```javascript
+const metrics = {
+  payment_initiated: counter('sepay_payment_initiated_total'),
+  payment_success: counter('sepay_payment_success_total'),
+  payment_failed: counter('sepay_payment_failed_total'),
+  webhook_received: counter('sepay_webhook_received_total'),
+  webhook_processed: counter('sepay_webhook_processed_total'),
+  api_errors: counter('sepay_api_errors_total'),
+  processing_time: histogram('sepay_processing_duration_seconds'),
+};
+
+// Track metrics
+metrics.payment_initiated.inc();
+const timer = metrics.processing_time.startTimer();
+// ... process payment
+timer();
+```
+
+### Structured Logging
+```javascript
+logger.info('Payment initiated', {
+  order_id: order.id,
+  amount: order.total,
+  payment_method: 'sepay',
+  customer_id: customer.id,
+});
+
+logger.info('Webhook received', {
+  transaction_id: webhook.id,
+  amount: webhook.transferAmount,
+  type: webhook.transferType,
+  reference: webhook.referenceCode,
+});
+
+logger.error('Payment failed', {
+  order_id: order.id,
+  error: error.message,
+  stack: error.stack,
+  sepay_response: response,
+});
+```
+
+### Alerting
+```javascript
+// Alert on high failure rate
+if (failureRate > 0.1) { // 10%
+  alert.send({
+    severity: 'high',
+    message: 'SePay payment failure rate exceeds 10%',
+    details: { failureRate, total, failed },
+  });
+}
+
+// Alert on webhook delivery failures
+if (webhookFailures > 10) {
+  alert.send({
+    severity: 'medium',
+    message: 'SePay webhook delivery failures',
+    details: { failures: webhookFailures },
+  });
+}
+```
+
+## Testing Strategy
+
+### Sandbox Testing Checklist
+- [ ] Successful payment flow
+- [ ] Failed payment handling
+- [ ] Canceled payment handling
+- [ ] Webhook delivery and processing
+- [ ] Duplicate webhook handling
+- [ ] Rate limit handling
+- [ ] Error scenarios (network, timeout, invalid data)
+- [ ] Payment verification via API
+- [ ] QR code generation
+- [ ] Order reconciliation
+
+### Load Testing
+```javascript
+// Simulate high volume
+for (let i = 0; i < 1000; i++) {
+  await createPayment({
+    amount: 100000,
+    orderId: `LOAD_TEST_${i}`,
+  });
+  await sleep(100); // Respect rate limits
+}
+```
+
+## Production Checklist
+
+- [ ] Environment variables configured
+- [ ] Production credentials obtained
+- [ ] HTTPS enabled for all endpoints
+- [ ] Webhook endpoint publicly accessible
+- [ ] IP whitelisting configured
+- [ ] Error monitoring set up
+- [ ] Logging infrastructure ready
+- [ ] Alerting configured
+- [ ] Rate limiting implemented
+- [ ] Database indexes created
+- [ ] Reconciliation job scheduled
+- [ ] Backup strategy in place
+- [ ] Documentation updated
+- [ ] Team trained on operations

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

@@ -0,0 +1,138 @@
+# SePay Overview
+
+Vietnamese payment automation platform serving as intermediary between applications and banks.
+
+## Core Capabilities
+
+**Payment Methods:**
+- VietQR - QR code bank transfers (NAPAS standard)
+- NAPAS QR - National payment gateway QR
+- Bank Cards - Visa/Mastercard/JCB
+- Bank Transfers - Direct bank-to-bank
+- Virtual Accounts - Order-specific VAs with exact matching
+
+**Supported Banks:** 44+ banks via NAPAS, 37+ with VietQR (Vietcombank, VPBank, BIDV, etc.)
+
+**Use Cases:**
+- Payment gateway for online payments
+- Bank API direct connection
+- Transaction verification automation
+- Real-time balance monitoring
+
+## Authentication
+
+### API Token (Simple)
+
+**Create:**
+1. Company Configuration → API Access → "+ Add API"
+2. Provide name, set status "Active"
+3. Copy token from list
+
+**Usage:**
+```
+Authorization: Bearer {API_TOKEN}
+Content-Type: application/json
+```
+
+**Note:** All tokens have full access (no permission levels currently)
+
+### OAuth2 (Advanced)
+
+**Scopes:**
+- `bank-account:read` - View accounts, balances
+- `transaction:read` - Transaction history
+- `webhook:read/write/delete` - Webhook management
+- `profile` - User information
+- `company` - Company details
+
+**Authorization Code Flow:**
+
+1. **Authorization Request:**
+```
+GET https://my.sepay.vn/oauth/authorize?
+  response_type=code&
+  client_id={CLIENT_ID}&
+  redirect_uri={REDIRECT_URI}&
+  scope={SCOPES}&
+  state={CSRF_TOKEN}
+```
+
+2. **Token Exchange (server-side only):**
+```
+POST https://my.sepay.vn/oauth/token
+{
+  "grant_type": "authorization_code",
+  "client_id": "{CLIENT_ID}",
+  "client_secret": "{CLIENT_SECRET}",
+  "code": "{AUTHORIZATION_CODE}"
+}
+```
+
+3. **Token Refresh:**
+```
+POST https://my.sepay.vn/oauth/token
+{
+  "grant_type": "refresh_token",
+  "refresh_token": "{REFRESH_TOKEN}",
+  "client_id": "{CLIENT_ID}",
+  "client_secret": "{CLIENT_SECRET}"
+}
+```
+
+**Security:** Access tokens expire ~1 hour, never expose client_secret, use state for CSRF protection
+
+## Payment Gateway Flow (13 Steps)
+
+1. Customer selects products, initiates payment
+2. Merchant creates order record
+3. Generate checkout form with HMAC-SHA256 signature
+4. Send request to `/v1/checkout/init`
+5. SePay validates signature
+6. Redirect customer to SePay gateway
+7. Customer selects payment method
+8. SePay communicates with banks/card networks
+9. Financial institution returns result
+10. Callback notification sent to merchant
+11. IPN (Instant Payment Notification) transmitted
+12. Customer redirected to merchant result page
+13. Final outcome displayed
+
+## Environments
+
+**Sandbox:**
+- Dashboard: https://my.sepay.vn (free tier)
+- Endpoint: https://sandbox.pay.sepay.vn/v1/init
+- Credentials: `SP-TEST-XXXXXXX`, `spsk_test_xxxxxxxxxxxxx`
+
+**Production:**
+- Endpoint: https://pay.sepay.vn/v1/init
+- Requirements: Personal/business bank account, completed testing
+- Approval: 3-7 days for NAPAS QR/cards (requires documentation)
+
+## Rate Limits
+
+**Limit:** 2 calls/second
+**Response:** HTTP 429 with `x-sepay-userapi-retry-after` header (seconds to wait)
+
+**Handling:**
+```javascript
+if (response.status === 429) {
+  const retryAfter = response.headers.get('x-sepay-userapi-retry-after');
+  await sleep(retryAfter * 1000);
+  return retry();
+}
+```
+
+## Support
+
+- Email: info@sepay.vn
+- Hotline: 02873059589 (24/7)
+- Docs: https://developer.sepay.vn/en
+- GitHub: https://github.com/sepayvn
+
+## Next Steps
+
+- **For API integration:** Load `api.md`
+- **For SDK integration:** Load `sdk.md`
+- **For webhook setup:** Load `webhooks.md`
+- **For QR generation:** Load `qr-codes.md`

package/dist/skills/payment-integration/references/sepay/qr-codes.md

@@ -0,0 +1,228 @@
+# SePay VietQR Generation
+
+Dynamic QR code generation service compatible with VietQR standard (NAPAS).
+
+## API Endpoint
+
+```
+https://qr.sepay.vn/img?acc={ACCOUNT}&bank={BANK}&amount={AMOUNT}&des={DESCRIPTION}
+```
+
+## Parameters
+
+**Required:**
+- `acc` - Bank account number
+- `bank` - Bank code or short name
+
+**Optional:**
+- `amount` - Transfer amount (omit for flexible amount)
+- `des` - Transfer description/content (URL encoded)
+- `template` - QR image template (empty/compact/qronly)
+- `download` - Set to "true" to download image
+
+## Examples
+
+### Complete QR (Fixed Amount)
+```
+https://qr.sepay.vn/img?
+  acc=0010000000355&
+  bank=Vietcombank&
+  amount=100000&
+  des=ung%20ho%20quy%20bao%20tro%20tre%20em
+```
+
+### Flexible QR (Customer Enters Amount)
+```
+https://qr.sepay.vn/img?acc=0010000000355&bank=Vietcombank
+```
+
+### QR Only Template
+```
+https://qr.sepay.vn/img?
+  acc=0010000000355&
+  bank=Vietcombank&
+  amount=100000&
+  template=qronly
+```
+
+## Integration
+
+### HTML
+```html
+<img src="https://qr.sepay.vn/img?acc=0010000000355&bank=Vietcombank&amount=100000"
+     alt="Payment QR Code" />
+```
+
+### JavaScript (Dynamic)
+```javascript
+function generatePaymentQR(account, bank, amount, description) {
+  const params = new URLSearchParams({
+    acc: account,
+    bank: bank,
+    amount: amount,
+    des: description
+  });
+  return `https://qr.sepay.vn/img?${params}`;
+}
+
+// Usage
+const qrUrl = generatePaymentQR(
+  '0010000000355',
+  'Vietcombank',
+  100000,
+  'Order #12345'
+);
+
+document.getElementById('qr-code').src = qrUrl;
+```
+
+### PHP (Dynamic)
+```php
+<?php
+function generatePaymentQR($account, $bank, $amount, $description) {
+    return 'https://qr.sepay.vn/img?' . http_build_query([
+        'acc' => $account,
+        'bank' => $bank,
+        'amount' => $amount,
+        'des' => $description
+    ]);
+}
+
+// Usage
+$qrUrl = generatePaymentQR(
+    '0010000000355',
+    'Vietcombank',
+    100000,
+    'Order #' . $orderId
+);
+
+echo "<img src='{$qrUrl}' alt='Payment QR' />";
+?>
+```
+
+### Node.js (Express)
+```javascript
+app.get('/payment/:orderId/qr', async (req, res) => {
+  const order = await Order.findById(req.params.orderId);
+
+  const qrUrl = new URL('https://qr.sepay.vn/img');
+  qrUrl.searchParams.set('acc', process.env.SEPAY_ACCOUNT);
+  qrUrl.searchParams.set('bank', process.env.SEPAY_BANK);
+  qrUrl.searchParams.set('amount', order.total);
+  qrUrl.searchParams.set('des', `Order ${order.id}`);
+
+  res.render('payment', { qrUrl: qrUrl.toString() });
+});
+```
+
+### React Component
+```jsx
+function PaymentQR({ account, bank, amount, description }) {
+  const qrUrl = useMemo(() => {
+    const params = new URLSearchParams({
+      acc: account,
+      bank: bank,
+      amount: amount,
+      des: description
+    });
+    return `https://qr.sepay.vn/img?${params}`;
+  }, [account, bank, amount, description]);
+
+  return (
+    <div className="payment-qr">
+      <img src={qrUrl} alt="Payment QR Code" />
+      <p>Scan to pay {amount.toLocaleString('vi-VN')} VND</p>
+    </div>
+  );
+}
+```
+
+## Templates
+
+**Default:**
+- Full QR with bank logo
+- Account information displayed
+- Branded with bank colors
+
+**Compact:**
+- Smaller version
+- Minimal branding
+- More space-efficient
+
+**QR Only:**
+- Pure QR code
+- No decorations
+- For custom layouts
+
+## Bank Codes
+
+**Get Bank List:**
+```
+GET https://qr.sepay.vn/banks.json
+```
+
+**Common Banks:**
+- Vietcombank (VCB)
+- VPBank
+- BIDV
+- Techcombank (TCB)
+- ACB
+- MB Bank
+- Sacombank
+- VietinBank
+- And 40+ others
+
+**Cache Bank List:**
+```javascript
+// Fetch once and cache
+const banks = await fetch('https://qr.sepay.vn/banks.json')
+  .then(res => res.json());
+
+// Store in memory or Redis
+cache.set('sepay_banks', banks, 86400); // 24 hours
+```
+
+## Best Practices
+
+1. **Cache Bank List:** Avoid repeated API calls
+2. **URL Encode Descriptions:** Use `encodeURIComponent()` or `http_build_query()`
+3. **Error Handling:** Provide fallback for QR generation failures
+4. **Amount Validation:** Ensure amount is positive integer
+5. **Flexible vs Fixed:** Use flexible QR for varying amounts
+6. **Template Selection:** Choose based on UI design
+7. **Responsive Design:** Scale QR code for mobile devices
+8. **Alt Text:** Always provide descriptive alt text
+9. **Loading State:** Show placeholder while QR loads
+10. **Print Support:** Ensure QR codes are print-friendly
+
+## Integration Patterns
+
+### Checkout Page
+```html
+<div class="payment-methods">
+  <h3>Pay via Bank Transfer</h3>
+  <img src="[QR_URL]" alt="Payment QR Code" class="qr-code" />
+  <p>Scan this QR code with your banking app</p>
+  <div class="payment-details">
+    <p><strong>Account:</strong> 0010000000355</p>
+    <p><strong>Bank:</strong> Vietcombank</p>
+    <p><strong>Amount:</strong> 100,000 VND</p>
+    <p><strong>Content:</strong> Order #12345</p>
+  </div>
+</div>
+```
+
+### Email Receipt
+```html
+<table>
+  <tr>
+    <td align="center">
+      <img src="[QR_URL]" alt="Payment QR Code" width="200" />
+      <p>Scan to pay for your order</p>
+    </td>
+  </tr>
+</table>
+```
+
+### PDF Invoice
+Use QR URL in PDF generation libraries (wkhtmltopdf, Puppeteer, etc.)