thanh-kit 2.5.0 → 2.5.2

package/templates/skills/payment-integration/references/creem/licensing.md

@@ -0,0 +1,136 @@
+# Creem.io Licensing
+
+Software licensing with device activation management.
+
+## License Flow
+
+```
+purchase → license_key issued → activate device → validate → deactivate
+```
+
+## Activate License
+
+Register a device against a license key:
+
+```javascript
+// POST /v1/licenses/activate
+const activation = await creem.licenses.activate({
+  license_key: 'XXXX-XXXX-XXXX-XXXX',
+  instance_id: 'device_fingerprint_123',  // Unique device identifier
+  instance_name: 'MacBook Pro'            // Optional friendly name
+});
+
+// Returns: {
+//   id: 'act_xxx',
+//   license_key: '...',
+//   instance_id: '...',
+//   activated_at: '...',
+//   valid_until: '...'
+// }
+```
+
+## Validate License
+
+Check if license is active for specific device:
+
+```javascript
+// POST /v1/licenses/validate
+const validation = await creem.licenses.validate({
+  license_key: 'XXXX-XXXX-XXXX-XXXX',
+  instance_id: 'device_fingerprint_123'
+});
+
+// Returns: {
+//   valid: true,
+//   license_key: '...',
+//   product_id: 'prod_xxx',
+//   customer_id: 'cus_xxx',
+//   expires_at: '2025-01-15T00:00:00Z',
+//   activations_used: 2,
+//   activations_limit: 5
+// }
+```
+
+## Deactivate License
+
+Remove device activation to free slot:
+
+```javascript
+// POST /v1/licenses/deactivate
+await creem.licenses.deactivate({
+  license_key: 'XXXX-XXXX-XXXX-XXXX',
+  instance_id: 'device_fingerprint_123'
+});
+```
+
+## Client-Side Implementation
+
+```javascript
+// Desktop app example (Electron, Tauri, etc.)
+class LicenseManager {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+    this.instanceId = this.getDeviceFingerprint();
+  }
+
+  getDeviceFingerprint() {
+    // Generate unique device ID (machine ID, hardware hash, etc.)
+    return require('node-machine-id').machineIdSync();
+  }
+
+  async activate(licenseKey) {
+    const response = await fetch('https://api.creem.io/v1/licenses/activate', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        license_key: licenseKey,
+        instance_id: this.instanceId,
+        instance_name: os.hostname()
+      })
+    });
+    return response.json();
+  }
+
+  async validate(licenseKey) {
+    const response = await fetch('https://api.creem.io/v1/licenses/validate', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        license_key: licenseKey,
+        instance_id: this.instanceId
+      })
+    });
+    const data = await response.json();
+    return data.valid;
+  }
+}
+```
+
+## Activation Limits
+
+Configure per product - limits simultaneous device activations:
+
+```javascript
+const product = await creem.products.create({
+  name: 'Desktop App License',
+  price: 4900,
+  currency: 'usd',
+  license_config: {
+    activations_limit: 3  // Max 3 devices per license
+  }
+});
+```
+
+## License Events (Webhooks)
+
+- `license.activated` - Device activated
+- `license.deactivated` - Device deactivated
+- `license.expired` - License expired (subscription ended)
+
+See `references/creem/webhooks.md` for webhook handling.

package/templates/skills/payment-integration/references/creem/overview.md

@@ -0,0 +1,65 @@
+# Creem.io Overview
+
+Payment infrastructure platform supporting subscriptions, one-time payments, and licensing. Functions as Merchant of Record (MoR) - handles compliance, taxes, and payment processing.
+
+## Key Features
+
+- **Merchant of Record**: Tax compliance, payment processing, global coverage
+- **Subscriptions**: Recurring billing, trials, seat-based, prorations
+- **One-Time Payments**: Single charges for products/services
+- **Licensing**: Activation keys, device management, validation
+- **Checkouts**: Hosted, embedded, no-code options
+- **Customer Portal**: Self-service billing management
+- **Revenue Splits**: Automatic payment distribution to multiple recipients
+
+## When to Choose Creem
+
+- Global SaaS products requiring MoR
+- Software licensing with activation management
+- Subscription products with seat-based billing
+- Digital product sales with file delivery
+- Affiliate/commission programs
+- Multi-recipient revenue splitting
+
+## Authentication
+
+```bash
+# API Key authentication
+curl -H "Authorization: Bearer sk_live_xxx" https://api.creem.io/v1/...
+```
+
+Environment variables:
+```bash
+CREEM_API_KEY=sk_live_xxx        # Production
+CREEM_API_KEY=sk_test_xxx        # Test mode
+CREEM_WEBHOOK_SECRET=whsec_xxx   # Webhook verification
+```
+
+## API Base URLs
+
+- **Production**: `https://api.creem.io/v1`
+- **Test Mode**: Use `sk_test_` prefixed API keys
+
+## Rate Limits
+
+Standard API rate limits apply. Check response headers for limit status.
+
+## Global Support
+
+- **Customers**: Hundreds of countries supported
+- **Merchants**: Global payouts
+- **Languages**: 42 languages for checkout localization
+
+## Related References
+
+- **API Endpoints**: `references/creem/api.md`
+- **Webhooks**: `references/creem/webhooks.md`
+- **Checkouts**: `references/creem/checkouts.md`
+- **Subscriptions**: `references/creem/subscriptions.md`
+- **Licensing**: `references/creem/licensing.md`
+- **SDKs**: `references/creem/sdk.md`
+
+## External Resources
+
+- **Documentation**: https://docs.creem.io
+- **LLM Docs**: https://docs.creem.io/llms.txt

package/templates/skills/payment-integration/references/creem/sdk.md

@@ -0,0 +1,161 @@
+# Creem.io SDKs
+
+## Official SDKs
+
+### Core SDK (`creem`)
+
+Full API access with maximum flexibility:
+
+```bash
+npm install creem
+# or
+pip install creem
+```
+
+```javascript
+// Node.js
+import Creem from 'creem';
+
+const creem = new Creem({
+  apiKey: process.env.CREEM_API_KEY
+});
+
+// Create checkout
+const session = await creem.checkout.sessions.create({
+  product_id: 'prod_xxx',
+  success_url: 'https://example.com/success'
+});
+```
+
+```python
+# Python
+from creem import Creem
+
+creem = Creem(api_key=os.environ['CREEM_API_KEY'])
+
+session = creem.checkout.sessions.create(
+    product_id='prod_xxx',
+    success_url='https://example.com/success'
+)
+```
+
+### Wrapper SDK (`creem_io`)
+
+Helper functions for common operations:
+
+```bash
+npm install creem_io
+```
+
+```javascript
+import { CreemClient, verifyWebhook } from 'creem_io';
+
+const client = new CreemClient({
+  apiKey: process.env.CREEM_API_KEY,
+  webhookSecret: process.env.CREEM_WEBHOOK_SECRET
+});
+
+// Simplified webhook verification
+app.post('/webhook', async (req, res) => {
+  const event = client.verifyWebhook(req.body, req.headers['x-creem-signature']);
+  // Handle event...
+});
+
+// Access management helpers
+const hasAccess = await client.checkAccess(customerId, productId);
+```
+
+## Framework Adapters
+
+### Next.js Adapter
+
+End-to-end billing integration:
+
+```bash
+npm install @creem/nextjs
+```
+
+```typescript
+// app/api/checkout/route.ts
+import { createCheckout } from '@creem/nextjs';
+
+export const POST = createCheckout({
+  productId: 'prod_xxx',
+  successUrl: '/success',
+  cancelUrl: '/pricing'
+});
+
+// app/api/webhooks/creem/route.ts
+import { handleWebhook } from '@creem/nextjs';
+
+export const POST = handleWebhook({
+  onCheckoutCompleted: async (session) => {
+    await grantAccess(session.customer_id);
+  },
+  onSubscriptionCancelled: async (subscription) => {
+    await revokeAccess(subscription.customer_id);
+  }
+});
+```
+
+### Better Auth Integration
+
+Combined auth + payments:
+
+```bash
+npm install @creem/better-auth
+```
+
+```typescript
+import { betterAuth } from 'better-auth';
+import { creemPlugin } from '@creem/better-auth';
+
+export const auth = betterAuth({
+  plugins: [
+    creemPlugin({
+      apiKey: process.env.CREEM_API_KEY,
+      webhookSecret: process.env.CREEM_WEBHOOK_SECRET,
+      products: {
+        pro: 'prod_xxx',
+        enterprise: 'prod_yyy'
+      }
+    })
+  ]
+});
+
+// Check subscription in auth session
+const session = await auth.getSession();
+if (session.user.subscription?.status === 'active') {
+  // User has active subscription
+}
+```
+
+### Next.js Template
+
+Pre-built starter with Prisma, shadcn/ui, Tailwind:
+
+```bash
+npx create-creem-app my-saas
+# or
+git clone https://github.com/creem-io/nextjs-template
+```
+
+Includes:
+- Auth (Better Auth)
+- Database (Prisma)
+- UI (shadcn/ui, Tailwind)
+- Pricing page
+- Customer portal
+- Webhook handling
+
+## Environment Variables
+
+```bash
+# .env
+CREEM_API_KEY=sk_live_xxx           # or sk_test_xxx for test mode
+CREEM_WEBHOOK_SECRET=whsec_xxx
+```
+
+## AI Tool Integration
+
+Creem supports Claude Code, Cursor, Windsurf via official skill - this document is part of that integration.

package/templates/skills/payment-integration/references/creem/subscriptions.md

@@ -0,0 +1,129 @@
+# Creem.io Subscriptions
+
+## Subscription Lifecycle
+
+```
+create → active → [pause] → [resume] → [upgrade] → cancel
+```
+
+## Create Subscription
+
+Via checkout session with recurring product:
+
+```javascript
+const session = await creem.checkout.sessions.create({
+  product_id: 'prod_recurring_xxx',
+  success_url: 'https://example.com/success',
+  customer_email: 'user@example.com'
+});
+```
+
+## Retrieve Subscription
+
+```javascript
+// GET /v1/subscriptions/:id
+const subscription = await creem.subscriptions.retrieve('sub_xxx');
+// Returns: { id, status, product_id, current_period_end, ... }
+```
+
+## Modify Subscription
+
+### Update Seats/Units
+
+```javascript
+// PATCH /v1/subscriptions/:id
+const updated = await creem.subscriptions.update('sub_xxx', {
+  quantity: 10,           // Seat count
+  prorate: true,          // Prorate charges
+  billing_immediately: false
+});
+```
+
+### Upgrade/Downgrade
+
+```javascript
+const updated = await creem.subscriptions.update('sub_xxx', {
+  product_id: 'prod_higher_tier',
+  prorate: true
+});
+```
+
+## Pause Subscription
+
+```javascript
+// POST /v1/subscriptions/:id/pause
+const paused = await creem.subscriptions.pause('sub_xxx', {
+  resume_at: '2024-02-01T00:00:00Z'  // Optional auto-resume date
+});
+```
+
+## Resume Subscription
+
+```javascript
+// POST /v1/subscriptions/:id/resume
+const resumed = await creem.subscriptions.resume('sub_xxx');
+```
+
+## Cancel Subscription
+
+```javascript
+// POST /v1/subscriptions/:id/cancel
+const cancelled = await creem.subscriptions.cancel('sub_xxx', {
+  at_period_end: true    // false = immediate cancellation
+});
+```
+
+## Free Trials
+
+Configure on product level:
+
+```javascript
+const product = await creem.products.create({
+  name: 'Pro Plan',
+  price: 2900,
+  currency: 'usd',
+  recurring: { interval: 'month' },
+  trial_period_days: 14
+});
+```
+
+## Seat-Based Billing
+
+```javascript
+const product = await creem.products.create({
+  name: 'Team Plan',
+  price: 1000,           // Per seat price
+  currency: 'usd',
+  recurring: { interval: 'month' },
+  billing_scheme: 'per_unit'
+});
+
+// Checkout with quantity
+const session = await creem.checkout.sessions.create({
+  product_id: 'prod_xxx',
+  quantity: 5,           // 5 seats
+  success_url: '...'
+});
+```
+
+## Product Bundles
+
+Group related tiers for upsells:
+
+```javascript
+const bundle = await creem.bundles.create({
+  name: 'Growth Plans',
+  products: ['prod_starter', 'prod_pro', 'prod_enterprise']
+});
+```
+
+## Subscription Events (Webhooks)
+
+- `subscription.created` - New subscription started
+- `subscription.updated` - Quantity, product, or status changed
+- `subscription.paused` - Subscription paused
+- `subscription.resumed` - Subscription resumed
+- `subscription.cancelled` - Cancellation scheduled or completed
+- `subscription.renewed` - Successful renewal charge
+
+See `references/creem/webhooks.md` for webhook handling.

package/templates/skills/payment-integration/references/creem/webhooks.md

@@ -0,0 +1,120 @@
+# Creem.io Webhooks
+
+## Webhook Setup
+
+Configure webhook endpoint in Creem dashboard. Receive events at your endpoint URL.
+
+## Event Types
+
+### Checkout Events
+- `checkout.completed` - Payment successful, access granted
+- `checkout.abandoned` - Cart abandoned (triggers recovery emails if enabled)
+
+### Subscription Events
+- `subscription.created` - New subscription started
+- `subscription.updated` - Changes to quantity, product, status
+- `subscription.paused` - Subscription paused
+- `subscription.resumed` - Subscription resumed
+- `subscription.cancelled` - Cancellation scheduled/completed
+- `subscription.renewed` - Successful renewal charge
+
+### Payment Events
+- `payment.succeeded` - Charge successful
+- `payment.failed` - Charge failed
+- `refund.created` - Refund processed
+- `chargeback.created` - Dispute opened
+
+### License Events
+- `license.activated` - Device activated against license
+- `license.deactivated` - Device deactivated
+
+## Webhook Payload Structure
+
+```json
+{
+  "id": "evt_xxx",
+  "type": "checkout.completed",
+  "created_at": "2024-01-15T10:30:00Z",
+  "data": {
+    "object": {
+      "id": "cs_xxx",
+      "customer_id": "cus_xxx",
+      "product_id": "prod_xxx",
+      "amount": 2900,
+      "currency": "usd",
+      "metadata": { "order_id": "123" }
+    }
+  }
+}
+```
+
+## Signature Verification
+
+```javascript
+import crypto from 'crypto';
+
+function verifyWebhook(payload, signature, secret) {
+  const expected = crypto
+    .createHmac('sha256', secret)
+    .update(payload, 'utf8')
+    .digest('hex');
+
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expected)
+  );
+}
+
+// Express handler
+app.post('/webhooks/creem', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['x-creem-signature'];
+  const payload = req.body.toString();
+
+  if (!verifyWebhook(payload, signature, process.env.CREEM_WEBHOOK_SECRET)) {
+    return res.status(401).send('Invalid signature');
+  }
+
+  const event = JSON.parse(payload);
+
+  switch (event.type) {
+    case 'checkout.completed':
+      await handleCheckoutCompleted(event.data.object);
+      break;
+    case 'subscription.cancelled':
+      await handleSubscriptionCancelled(event.data.object);
+      break;
+  }
+
+  res.status(200).send('OK');
+});
+```
+
+## Idempotency
+
+Store processed event IDs to prevent duplicate processing:
+
+```javascript
+async function handleWebhook(event) {
+  // Check if already processed
+  const existing = await db.webhookEvents.findOne({ eventId: event.id });
+  if (existing) return { status: 'already_processed' };
+
+  // Process event
+  await processEvent(event);
+
+  // Mark as processed
+  await db.webhookEvents.create({
+    eventId: event.id,
+    type: event.type,
+    processedAt: new Date()
+  });
+}
+```
+
+## Retry Behavior
+
+Creem retries failed webhooks (non-2xx responses). Implement idempotency to handle retries safely.
+
+## Testing Webhooks
+
+Use test mode API keys (`sk_test_`) - events sent to same webhook endpoint with test data.

package/templates/skills/payment-integration/references/implementation-workflows.md

@@ -0,0 +1,43 @@
+# Implementation Workflows
+
+## SePay Implementation
+1. Load `references/sepay/overview.md` for auth setup
+2. Load `references/sepay/api.md` or `references/sepay/sdk.md` for integration
+3. Load `references/sepay/webhooks.md` for payment notifications
+4. Use `scripts/sepay-webhook-verify.js` for webhook verification
+5. Load `references/sepay/best-practices.md` for production readiness
+
+## Polar Implementation
+1. Load `references/polar/overview.md` for auth and concepts
+2. Load `references/polar/products.md` for product setup
+3. Load `references/polar/checkouts.md` for payment flows
+4. Load `references/polar/webhooks.md` for event handling
+5. Use `scripts/polar-webhook-verify.js` for webhook verification
+6. Load `references/polar/benefits.md` if automating delivery
+7. Load `references/polar/best-practices.md` for production readiness
+
+## Stripe Implementation
+1. Load `references/stripe/stripe-best-practices.md` for integration design
+2. Load `references/stripe/stripe-sdks.md` for server-side SDK setup
+3. Load `references/stripe/stripe-js.md` for client-side Elements/Checkout
+4. Use `stripe listen` via CLI for local webhook testing (`references/stripe/stripe-cli.md`)
+5. Choose integration: Checkout (hosted/embedded) or Payment Element
+6. Use CheckoutSessions API for most payment flows
+7. Use Billing APIs for subscriptions (combine with Checkout)
+8. Load `references/stripe/stripe-upgrade.md` when upgrading API versions
+
+## Creem.io Implementation
+1. Load `references/creem/overview.md` for auth and MoR concepts
+2. Load `references/creem/api.md` for products and checkout sessions
+3. Load `references/creem/checkouts.md` for payment flow options
+4. Load `references/creem/webhooks.md` for event handling
+5. Load `references/creem/subscriptions.md` if implementing recurring billing
+6. Load `references/creem/licensing.md` if implementing device activation
+7. Load `references/creem/sdk.md` for framework-specific adapters
+
+## General Workflow
+1. Identify platform (Vietnamese → SePay, global SaaS → Polar/Stripe/Creem.io)
+2. Load relevant references progressively
+3. Implement: auth → products → checkout → webhooks → events
+4. Test in sandbox, then production
+5. Load only needed references to maintain context efficiency