anchi-kit 1.2.0 → 1.2.2

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

@@ -1,337 +0,0 @@
-# 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/.antigravity/skills/payment-integration/references/sepay/overview.md

@@ -1,138 +0,0 @@
-# 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/.antigravity/skills/payment-integration/references/sepay/qr-codes.md

@@ -1,228 +0,0 @@
-# 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.)