anchi-kit 1.2.0 → 1.2.2

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

@@ -1,213 +0,0 @@
-# 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/.cursor/skills/payment-integration/references/sepay/webhooks.md

@@ -1,208 +0,0 @@
-# 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/.cursor/skills/payment-integration/scripts/.env.example

@@ -1,20 +0,0 @@
-# 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/.cursor/skills/payment-integration/scripts/checkout-helper.js

@@ -1,244 +0,0 @@
-#!/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/.cursor/skills/payment-integration/scripts/package.json

@@ -1,17 +0,0 @@
-{
-  "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"
-}