anchi-kit 1.2.0 → 1.2.2

package/.antigravity/skills/payment-integration/references/polar/webhooks.md

@@ -1,405 +0,0 @@
-# Polar Webhooks
-
-Event handling, signature verification, and monitoring.
-
-## Setup
-
-1. Org Settings → Webhooks
-2. Enter endpoint URL (publicly accessible)
-3. Receive webhook secret (base64 encoded)
-4. Select event types
-5. Save configuration
-
-**Requirements:**
-- HTTPS endpoint
-- Respond within 20 seconds
-- Return 2xx status code
-
-## Signature Verification
-
-### Headers
-```
-webhook-id: msg_xxx
-webhook-signature: v1,signature_xxx
-webhook-timestamp: 1642000000
-```
-
-### TypeScript Verification
-```typescript
-import { validateEvent, WebhookVerificationError } from '@polar-sh/sdk/webhooks';
-
-app.post('/webhook/polar', (req, res) => {
-  try {
-    const event = validateEvent(
-      req.body,
-      req.headers,
-      process.env.POLAR_WEBHOOK_SECRET
-    );
-
-    // Event is valid, process it
-    await handleEvent(event);
-
-    res.json({ received: true });
-  } catch (error) {
-    if (error instanceof WebhookVerificationError) {
-      console.error('Invalid webhook signature');
-      return res.status(400).json({ error: 'Invalid signature' });
-    }
-    throw error;
-  }
-});
-```
-
-### Python Verification
-```python
-from polar_sdk.webhooks import validate_event, WebhookVerificationError
-
-@app.route('/webhook/polar', methods=['POST'])
-def polar_webhook():
-    try:
-        event = validate_event(
-            request.get_data(),
-            dict(request.headers),
-            os.environ['POLAR_WEBHOOK_SECRET']
-        )
-
-        handle_event(event)
-        return {'received': True}
-
-    except WebhookVerificationError:
-        return {'error': 'Invalid signature'}, 400
-```
-
-### Manual Verification
-```typescript
-import crypto from 'crypto';
-
-function verifySignature(payload, headers, secret) {
-  const timestamp = headers['webhook-timestamp'];
-  const signatures = headers['webhook-signature'].split(',');
-
-  const signedPayload = `${timestamp}.${payload}`;
-  const expectedSignature = crypto
-    .createHmac('sha256', Buffer.from(secret, 'base64'))
-    .update(signedPayload)
-    .digest('base64');
-
-  return signatures.some(sig => {
-    const [version, signature] = sig.split('=');
-    return version === 'v1' && signature === expectedSignature;
-  });
-}
-```
-
-## Event Types
-
-### Checkout
-- `checkout.created` - Checkout session created
-- `checkout.updated` - Session updated
-
-### Order
-- `order.created` - Order created (check `billing_reason`)
-  - `purchase` - One-time product
-  - `subscription_create` - New subscription
-  - `subscription_cycle` - Renewal
-  - `subscription_update` - Plan change
-- `order.paid` - Payment confirmed
-- `order.updated` - Order updated
-- `order.refunded` - Refund processed
-
-### Subscription
-- `subscription.created` - Subscription created
-- `subscription.active` - Subscription activated
-- `subscription.updated` - Subscription modified
-- `subscription.canceled` - Cancellation scheduled
-- `subscription.revoked` - Subscription terminated
-
-**Note:** Multiple events may fire for single action
-
-### Customer
-- `customer.created` - Customer created
-- `customer.updated` - Customer modified
-- `customer.deleted` - Customer deleted
-- `customer.state_changed` - Benefits/subscriptions changed
-
-### Benefit Grant
-- `benefit_grant.created` - Benefit granted
-- `benefit_grant.updated` - Grant modified
-- `benefit_grant.revoked` - Benefit revoked
-
-### Refund
-- `refund.created` - Refund initiated
-- `refund.updated` - Refund status changed
-
-### Product
-- `product.created` - Product created
-- `product.updated` - Product modified
-
-## Event Structure
-
-```typescript
-{
-  "type": "order.paid",
-  "data": {
-    "id": "order_xxx",
-    "amount": 2000,
-    "currency": "USD",
-    "billing_reason": "purchase",
-    "customer": { ... },
-    "product": { ... },
-    "subscription": null,
-    "metadata": { ... }
-  }
-}
-```
-
-## Handler Implementation
-
-### Basic Handler
-```typescript
-async function handleEvent(event) {
-  switch (event.type) {
-    case 'order.paid':
-      await handleOrderPaid(event.data);
-      break;
-
-    case 'subscription.active':
-      await grantAccess(event.data.customer_id);
-      break;
-
-    case 'subscription.revoked':
-      await revokeAccess(event.data.customer_id);
-      break;
-
-    case 'benefit_grant.created':
-      await notifyBenefitGranted(event.data);
-      break;
-
-    default:
-      console.log(`Unhandled event: ${event.type}`);
-  }
-}
-```
-
-### Order Handler
-```typescript
-async function handleOrderPaid(order) {
-  // Handle different billing reasons
-  switch (order.billing_reason) {
-    case 'purchase':
-      await fulfillOneTimeOrder(order);
-      break;
-
-    case 'subscription_create':
-      await handleNewSubscription(order);
-      break;
-
-    case 'subscription_cycle':
-      await handleRenewal(order);
-      break;
-
-    case 'subscription_update':
-      await handleUpgrade(order);
-      break;
-  }
-}
-```
-
-### Customer State Handler
-```typescript
-async function handleCustomerStateChanged(customer) {
-  // Customer state includes:
-  // - active_subscriptions
-  // - active_benefits
-
-  const hasActiveSubscription = customer.active_subscriptions.length > 0;
-
-  if (hasActiveSubscription) {
-    await enableFeatures(customer.external_id);
-  } else {
-    await disableFeatures(customer.external_id);
-  }
-}
-```
-
-## Best Practices
-
-### 1. Respond Immediately
-```typescript
-app.post('/webhook/polar', async (req, res) => {
-  // Respond quickly
-  res.json({ received: true });
-
-  // Queue for background processing
-  await webhookQueue.add('polar-webhook', req.body);
-});
-```
-
-### 2. Idempotency
-```typescript
-async function handleEvent(event) {
-  // Check if already processed
-  const exists = await db.processedEvents.findOne({
-    webhook_id: event.id
-  });
-
-  if (exists) {
-    console.log('Event already processed');
-    return;
-  }
-
-  // Process event
-  await processEvent(event);
-
-  // Mark as processed
-  await db.processedEvents.insert({
-    webhook_id: event.id,
-    processed_at: new Date()
-  });
-}
-```
-
-### 3. Retry Logic
-```typescript
-async function processWithRetry(event, maxRetries = 3) {
-  let attempt = 0;
-
-  while (attempt < maxRetries) {
-    try {
-      await handleEvent(event);
-      return;
-    } catch (error) {
-      attempt++;
-      if (attempt >= maxRetries) throw error;
-      await sleep(1000 * attempt);
-    }
-  }
-}
-```
-
-### 4. Error Handling
-```typescript
-app.post('/webhook/polar', async (req, res) => {
-  try {
-    const event = validateEvent(req.body, req.headers, secret);
-    res.json({ received: true });
-
-    await processWithRetry(event);
-  } catch (error) {
-    console.error('Webhook processing failed:', error);
-    // Log to error tracking service
-    await logError(error, req.body);
-
-    if (error instanceof WebhookVerificationError) {
-      return res.status(400).json({ error: 'Invalid signature' });
-    }
-
-    // Return 2xx even on processing errors
-    // Polar will retry if non-2xx
-    res.json({ received: true });
-  }
-});
-```
-
-### 5. Logging
-```typescript
-logger.info('Webhook received', {
-  event_type: event.type,
-  event_id: event.id,
-  customer_id: event.data.customer?.id,
-  amount: event.data.amount
-});
-```
-
-## Monitoring
-
-### Dashboard Features
-- View webhook attempts
-- Check response status
-- Review retry history
-- Manual retry option
-- Filter by event type
-- Search by customer
-
-### Application Monitoring
-```typescript
-const metrics = {
-  webhooks_received: counter('polar_webhooks_received_total'),
-  webhooks_processed: counter('polar_webhooks_processed_total'),
-  webhooks_failed: counter('polar_webhooks_failed_total'),
-  processing_time: histogram('polar_webhook_processing_seconds')
-};
-
-app.post('/webhook/polar', async (req, res) => {
-  metrics.webhooks_received.inc({ type: req.body.type });
-
-  const timer = metrics.processing_time.startTimer();
-
-  try {
-    await handleEvent(req.body);
-    metrics.webhooks_processed.inc({ type: req.body.type });
-  } catch (error) {
-    metrics.webhooks_failed.inc({ type: req.body.type });
-  } finally {
-    timer();
-  }
-
-  res.json({ received: true });
-});
-```
-
-## Framework Adapters
-
-### Next.js
-```typescript
-import { validateEvent } from '@polar-sh/nextjs/webhooks';
-
-export async function POST(req: Request) {
-  const event = await validateEvent(req);
-
-  await handleEvent(event);
-
-  return Response.json({ received: true });
-}
-```
-
-### Laravel
-```php
-use Polar\Webhooks\WebhookHandler;
-
-Route::post('/webhook/polar', function (Request $request) {
-    $event = WebhookHandler::validate(
-        $request->getContent(),
-        $request->headers->all(),
-        config('polar.webhook_secret')
-    );
-
-    dispatch(new ProcessPolarWebhook($event));
-
-    return response()->json(['received' => true]);
-});
-```
-
-## Testing
-
-### Manual Testing
-```bash
-# Use Polar dashboard to send test webhooks
-# Or use webhook testing tools
-
-curl -X POST https://your-domain.com/webhook/polar \
-  -H "Content-Type: application/json" \
-  -H "webhook-id: msg_test" \
-  -H "webhook-timestamp: $(date +%s)" \
-  -H "webhook-signature: v1,test_signature" \
-  -d '{"type":"order.paid","data":{...}}'
-```
-
-### Local Testing with ngrok
-```bash
-# Expose local server
-ngrok http 3000
-
-# Use ngrok URL in Polar webhook settings
-https://abc123.ngrok.io/webhook/polar
-```

package/.antigravity/skills/payment-integration/references/sepay/api.md

@@ -1,140 +0,0 @@
-# SePay API Reference
-
-Base URL: `https://my.sepay.vn/userapi/`
-Rate Limit: 2 calls/second
-
-## Transaction API
-
-### List Transactions
-```
-GET /userapi/transactions/list
-```
-
-**Parameters:**
-- `account_number` (string) - Bank account ID
-- `transaction_date_min/max` (yyyy-mm-dd) - Date range
-- `since_id` (integer) - Start from ID
-- `limit` (integer) - Max 5000 per request
-- `reference_number` (string) - Transaction reference
-- `amount_in` (number) - Incoming amount
-- `amount_out` (number) - Outgoing amount
-
-**Response:**
-```json
-{
-  "status": 200,
-  "transactions": [{
-    "id": 92704,
-    "gateway": "Vietcombank",
-    "transaction_date": "2023-03-25 14:02:37",
-    "account_number": "0123499999",
-    "content": "payment content",
-    "transfer_type": "in",
-    "transfer_amount": 2277000,
-    "accumulated": 19077000,
-    "reference_number": "MBVCB.3278907687",
-    "bank_account_id": 123
-  }]
-}
-```
-
-### Transaction Details
-```
-GET /userapi/transactions/details/{transaction_id}
-```
-
-### Count Transactions
-```
-GET /userapi/transactions/count
-```
-
-## Bank Account API
-
-### List Bank Accounts
-```
-GET /userapi/bankaccounts/list
-```
-
-**Parameters:**
-- `short_name` - Bank identifier
-- `last_transaction_date_min/max` - Date range
-- `since_id` - Starting account ID
-- `limit` - Results per page (default 100)
-- `accumulated_min/max` - Balance range
-
-**Response:**
-```json
-{
-  "id": 123,
-  "account_holder_name": "NGUYEN VAN A",
-  "account_number": "0123456789",
-  "accumulated": 50000000,
-  "last_transaction": "2025-01-13 10:30:00",
-  "bank_short_name": "VCB",
-  "active": 1
-}
-```
-
-### Account Details
-```
-GET /userapi/bankaccounts/details/{bank_account_id}
-```
-
-### Count Accounts
-```
-GET /userapi/bankaccounts/count
-```
-
-## Order-Based Virtual Account API
-
-**Concept:** Each order gets unique VA with exact amount matching for automated confirmation.
-
-**Flow:**
-1. Create order → API generates unique VA
-2. Display VA + QR to customer
-3. Customer transfers to VA
-4. Bank notifies SePay on success
-5. SePay triggers webhook
-6. Update order status
-
-**Advantages:**
-- Precision: VA accepts only exact amounts
-- Independence: Each order has own VA (no content parsing)
-- Security: VAs auto-cancel after success/expiration
-- Integration: RESTful API
-
-**Supported Banks:** BIDV and others (check docs for full list)
-
-## Error Handling
-
-**HTTP Status Codes:**
-- 200 OK - Successful
-- 201 Created - Resource created
-- 400 Bad Request - Invalid parameters
-- 401 Unauthorized - Invalid/missing auth
-- 403 Forbidden - Insufficient permissions
-- 404 Not Found - Resource not found
-- 429 Too Many Requests - Rate limit exceeded
-- 500 Internal Server Error - Server error
-- 503 Service Unavailable - Temporarily unavailable
-
-**Rate Limit Response:**
-```json
-{
-  "status": 429,
-  "error": "rate_limit_exceeded",
-  "message": "Too many requests"
-}
-```
-
-Check `x-sepay-userapi-retry-after` header for retry timing.
-
-## Best Practices
-
-1. **Pagination:** Use `limit` and `since_id` for large datasets
-2. **Date Ranges:** Query specific periods to reduce response size
-3. **Rate Limiting:** Implement exponential backoff
-4. **Error Handling:** Log all errors with context
-5. **Caching:** Cache bank account lists
-6. **Monitoring:** Track API response times and error rates
-7. **Reconciliation:** Regular transaction matching