vibes-plug 2.14.1 → 3.9.0

package/skills/mvc-expert/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: mvc-expert
 description: "Expert guidelines to refactor legacy PHP codebases into clean, modern, and scalable MVC-structured projects / Pedoman ahli untuk merefaktor codebase PHP lama menjadi proyek terstruktur MVC yang bersih, modern, dan skalabel."
-author: "Roedy Rustam"
+author: "Roedy Rustam"
+version: "3.0.0"
 ---
 
 # PHP MVC Expert & Modernization
@@ -14,7 +15,7 @@ author: "Roedy Rustam"
 ## English
 
 ### Orchestration & Integration
-Connects and orchestrates with relevant domain skills like `brainstorming`, `zero-to-prod-orchestrator`, and `project-context-mapper` to ensure cohesive execution.
+Connects and orchestrates with relevant domain skills like `brainstorming`, `zero-to-prod-orchestrator`, and `session-memory-manager` to ensure cohesive execution.
 
 ### Description
 This skill provides the agent with structured protocols, coding patterns, and architectural guidelines to audit, refactor, and modernize legacy/obsolete PHP codebases (plain spaghetti PHP) into a clean, modern, secure, and scalable Model-View-Controller (MVC) structure adhering to PSR standards and modern PHP (v8.2+) capabilities.
@@ -128,7 +129,7 @@ Active whenever the user requests to:
 ## Bahasa Indonesia
 
 ### Integrasi Orkestrasi
-Terhubung dan mengorkestrasi skill domain yang relevan seperti `brainstorming`, `zero-to-prod-orchestrator`, dan `project-context-mapper` untuk memastikan eksekusi yang kohesif.
+Terhubung dan mengorkestrasi skill domain yang relevan seperti `brainstorming`, `zero-to-prod-orchestrator`, dan `session-memory-manager` untuk memastikan eksekusi yang kohesif.
 
 ### Deskripsi
 Skill ini memberikan protokol terstruktur, pola penulisan kode, dan panduan arsitektur bagi agen untuk melakukan audit, refaktorisasi, dan modernisasi terhadap codebase PHP lama yang usang (Plain Spaghetti PHP) menjadi struktur Model-View-Controller (MVC) yang bersih, modern, aman, dan skalabel yang mematuhi standar PSR serta kemampuan PHP modern (v8.2+).
@@ -234,4 +235,4 @@ Saat mengatur proyek sebagai Multi-Page Application di dalam satu repositori, ik
 Aktif setiap kali pengguna meminta untuk:
 - Memodernisasi proyek PHP lama atau script PHP spageti.
 - Merancang arsitektur MVC atau memperkenalkan pola routing yang bersih di plain PHP.
-- Menerapkan pemrograman berorientasi objek (OOP), namespace Composer (PSR-4), atau membersihkan akses database via PDO pada aplikasi PHP.
+- Menerapkan pemrograman berorientasi objek (OOP), namespace Composer (PSR-4), atau membersihkan akses database via PDO pada aplikasi PHP.

package/skills/n8n-automation-expert/SKILL.md

@@ -1,89 +1,90 @@
----
-name: n8n-automation-expert
-description: "Expert guide for workflow automation (n8n, Zapier, Make), custom nodes, webhook triggers, and AI-powered automation chains / Panduan ahli otomasi workflow (n8n, Zapier, Make), custom nodes, webhook triggers, dan rantai otomasi berbasis AI."
-author: "Roedy Rustam"
----
-
-# Workflow Automation Expert (2026 Edition)
-
-[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
----
-
-<a name="english"></a>
-## English
-
-### Orchestration & Integration
-- **`cron-scheduler-expert`**: Scheduled triggers for automation workflows.
-- **`ai-llm-integration-expert`**: AI-powered automation steps and LLM chains.
-- **`email-notification-expert`**: Email triggers and notification actions.
-- **`webhook-receiver`**: Webhook endpoints as automation triggers.
-
-### Description
-Expert guide for building automation workflows with n8n (self-hosted, open-source), Zapier, and Make (Integromat). Covers workflow design, custom n8n nodes, webhook triggers, AI chains within workflows, error handling, credential management, and integration patterns with databases, APIs, and messaging platforms.
-
-### Trigger Conditions
-- Building automated workflows connecting multiple services.
-- Setting up n8n for self-hosted automation.
-- Creating AI-powered automation pipelines.
-- Integrating no-code/low-code automation with custom applications.
-
----
-
-### Platform Selection
-
-| Platform | Hosting | Custom Code | AI Support | Pricing | Best For |
-|----------|---------|-------------|------------|---------|----------|
-| n8n | Self-hosted/Cloud | ✅ Full | ✅ AI nodes | Free (self) | Developers, privacy |
-| Zapier | Cloud only | Limited | ✅ AI actions | $29+/mo | Non-technical teams |
-| Make | Cloud only | ✅ Modules | ✅ AI modules | $10+/mo | Visual workflows |
-
-**Recommendation:** Use **n8n** for developer teams needing full control and self-hosting. Use **Zapier** for simple integrations by non-technical users.
-
-### n8n Core Patterns
-
-```typescript
-// Custom n8n node — AI Content Processor
-import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
-
-export class AiContentProcessor implements INodeType {
-  description: INodeTypeDescription = {
-    displayName: 'AI Content Processor',
-    name: 'aiContentProcessor',
-    group: ['transform'],
-    version: 1,
-    inputs: ['main'],
-    outputs: ['main'],
-    properties: [
-      { displayName: 'Prompt Template', name: 'prompt', type: 'string', default: '' },
-      { displayName: 'Model', name: 'model', type: 'options', options: [
-        { name: 'GPT-4o', value: 'gpt-4o' },
-        { name: 'Claude 4 Sonnet', value: 'claude-4-sonnet' },
-      ], default: 'gpt-4o' },
-    ],
-  };
-
-  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
-    const items = this.getInputData();
-    const prompt = this.getNodeParameter('prompt', 0) as string;
-    // Process each item with AI...
-    return [items];
-  }
-}
-```
-
-## Orchestration & Integration
-- `cron-scheduler-expert`, `ai-llm-integration-expert`, `webhook-receiver`
-
----
-
-<a name="bahasa-indonesia"></a>
-## Bahasa Indonesia
-
-### Deskripsi
-Panduan ahli untuk membangun alur kerja otomatis dengan n8n, Zapier, dan Make. Mencakup desain workflow, custom nodes n8n, webhook triggers, rantai AI, dan integrasi dengan database dan API.
-
-### Kondisi Pemicu
-- Membangun alur kerja otomatis yang menghubungkan beberapa layanan.
-- Menyiapkan n8n untuk otomasi self-hosted.
-- Membuat pipeline otomasi berbasis AI.
+---
+name: n8n-automation-expert
+description: "Expert guide for workflow automation (n8n, Zapier, Make), custom nodes, webhook triggers, and AI-powered automation chains / Panduan ahli otomasi workflow (n8n, Zapier, Make), custom nodes, webhook triggers, dan rantai otomasi berbasis AI."
+author: "Roedy Rustam"
+version: "3.0.0"
+---
+
+# Workflow Automation Expert (2026 Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Orchestration & Integration
+- **`cron-scheduler-expert`**: Scheduled triggers for automation workflows.
+- **`ai-llm-integration-expert`**: AI-powered automation steps and LLM chains.
+- **`email-notification-expert`**: Email triggers and notification actions.
+- **`webhook-receiver`**: Webhook endpoints as automation triggers.
+
+### Description
+Expert guide for building automation workflows with n8n (self-hosted, open-source), Zapier, and Make (Integromat). Covers workflow design, custom n8n nodes, webhook triggers, AI chains within workflows, error handling, credential management, and integration patterns with databases, APIs, and messaging platforms.
+
+### Trigger Conditions
+- Building automated workflows connecting multiple services.
+- Setting up n8n for self-hosted automation.
+- Creating AI-powered automation pipelines.
+- Integrating no-code/low-code automation with custom applications.
+
+---
+
+### Platform Selection
+
+| Platform | Hosting | Custom Code | AI Support | Pricing | Best For |
+|----------|---------|-------------|------------|---------|----------|
+| n8n | Self-hosted/Cloud | ✅ Full | ✅ AI nodes | Free (self) | Developers, privacy |
+| Zapier | Cloud only | Limited | ✅ AI actions | $29+/mo | Non-technical teams |
+| Make | Cloud only | ✅ Modules | ✅ AI modules | $10+/mo | Visual workflows |
+
+**Recommendation:** Use **n8n** for developer teams needing full control and self-hosting. Use **Zapier** for simple integrations by non-technical users.
+
+### n8n Core Patterns
+
+```typescript
+// Custom n8n node — AI Content Processor
+import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+
+export class AiContentProcessor implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'AI Content Processor',
+    name: 'aiContentProcessor',
+    group: ['transform'],
+    version: 1,
+    inputs: ['main'],
+    outputs: ['main'],
+    properties: [
+      { displayName: 'Prompt Template', name: 'prompt', type: 'string', default: '' },
+      { displayName: 'Model', name: 'model', type: 'options', options: [
+        { name: 'GPT-4o', value: 'gpt-4o' },
+        { name: 'Claude 4 Sonnet', value: 'claude-4-sonnet' },
+      ], default: 'gpt-4o' },
+    ],
+  };
+
+  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
+    const items = this.getInputData();
+    const prompt = this.getNodeParameter('prompt', 0) as string;
+    // Process each item with AI...
+    return [items];
+  }
+}
+```
+
+## Orchestration & Integration
+- `cron-scheduler-expert`, `ai-llm-integration-expert`, `webhook-receiver`
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Panduan ahli untuk membangun alur kerja otomatis dengan n8n, Zapier, dan Make. Mencakup desain workflow, custom nodes n8n, webhook triggers, rantai AI, dan integrasi dengan database dan API.
+
+### Kondisi Pemicu
+- Membangun alur kerja otomatis yang menghubungkan beberapa layanan.
+- Menyiapkan n8n untuk otomasi self-hosted.
+- Membuat pipeline otomasi berbasis AI.

package/skills/nextjs-app-router-expert/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: nextjs-app-router-expert
 description: "Expert guide for Next.js 15 App Router: RSC, Server Actions, Middleware, Parallel/Intercepting Routes, Streaming, and Caching strategies / Panduan ahli untuk Next.js 15 App Router."
-author: "Roedy Rustam"
+author: "Roedy Rustam"
+version: "3.0.0"
 ---
 
 # Next.js 15 App Router Expert
@@ -145,4 +146,4 @@ Bungkus pengambilan data lambat dengan `<Suspense>` untuk menampilkan UI awal se
 - **`senior-frontend`**: Menguatkan UI/UX dengan pemahaman arsitektur RSC dan cache Next 15.
 - **`js-backend-expert`**: Menghubungkan Server Actions dengan arsitektur backend Node.js/Bun.
 - **`tanstack-query-expert`**: Mengelola hidrasi state client-side dari RSC.
-- **`performance-web-vitals`**: Optimalisasi Core Web Vitals menggunakan Streaming dan PPR.
+- **`performance-web-vitals`**: Optimalisasi Core Web Vitals menggunakan Streaming dan PPR.

package/skills/openapi-swagger-codegen-expert/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: openapi-swagger-codegen-expert
 description: "OpenAPI 3.1 spec authoring, Swagger UI, automatic client/server code generation (openapi-typescript, Orval, Kiota), contract testing / Penulisan spesifikasi OpenAPI 3.1, Swagger UI, pembuatan kode klien/server otomatis, dan pengujian kontrak."
-author: "Roedy Rustam"
+author: "Roedy Rustam"
+version: "3.0.0"
 ---
 
 # OpenAPI & Swagger Codegen Expert
@@ -39,7 +40,7 @@ Dedicated expert guide for API contract-first development using OpenAPI 3.1, Swa
 ## Bahasa Indonesia
 
 ### Integrasi Orkestrasi
-Terhubung dan mengorkestrasi skill domain yang relevan seperti `brainstorming`, `zero-to-prod-orchestrator`, dan `project-context-mapper` untuk memastikan eksekusi yang kohesif.
+Terhubung dan mengorkestrasi skill domain yang relevan seperti `brainstorming`, `zero-to-prod-orchestrator`, dan `session-memory-manager` untuk memastikan eksekusi yang kohesif.
 
 ### Deskripsi
 Panduan ahli khusus untuk pengembangan API dengan pendekatan *contract-first* menggunakan OpenAPI 3.1, Swagger UI, dan otomatisasi pembuatan kode (codegen). Mencakup pembuatan klien API yang *strictly typed* (menggunakan `openapi-typescript`, `Orval`, atau Microsoft `Kiota`), *scaffolding* untuk server, dan implementasi *contract testing* untuk memastikan backend selalu sesuai dengan dokumentasinya.
@@ -64,4 +65,4 @@ Panduan ahli khusus untuk pengembangan API dengan pendekatan *contract-first* me
 ## Orchestration & Integration
 - Connects to `api-design-expert` for the core design rules.
 - Connects to `ci-cd-devops-architect` to implement CI/CD validation.
-- Connects to `senior-frontend` / `tanstack-query-expert` to consume the generated clients.
+- Connects to `senior-frontend` / `tanstack-query-expert` to consume the generated clients.

package/skills/payment-gateway-expert/SKILL.md

@@ -1,129 +1,132 @@
----
-name: payment-gateway-expert
-description: "Expert guide for integrating payment gateways (Stripe, PayPal, Xendit, Midtrans, DOKU) and secure webhooks into SaaS platforms / Panduan ahli integrasi payment gateway dan webhook aman."
+---
+name: payment-gateway-expert
+description: "Expert guide for integrating payment gateways (Stripe, PayPal, Xendit, Midtrans, DOKU SNAP BI) and secure webhooks into SaaS platforms / Panduan ahli integrasi payment gateway dan webhook aman."
 author: "Roedy Rustam"
----
-
-# Payment Gateway Expert / Ahli Payment Gateway
-
-[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
----
-
-<a name="english"></a>
-## English
-
-### Description
-Expert guide for integrating major payment gateways (Stripe, PayPal, Xendit, Midtrans, DOKU) into modern SaaS platforms. Covers checkout flows, secure webhook handling, subscription management, and synchronization with local databases.
-
-### Instructions
-- **Security First**: Always validate webhook signatures before processing any payment event. Never trust client-side data for prices or payment status. For DOKU, ensure signature components (like request target) are arranged strictly according to documentation.
-- **Idempotency**: Implement idempotency keys for all payment creation requests to avoid duplicate charges. Webhook handlers must also be idempotent. For DOKU, include a unique `Request-Id` header.
-- **State Synchronization**: Ensure the local database (e.g., PostgreSQL, Supabase) is updated immediately and transactionally upon receiving successful webhook events.
-- **Subscription Management**: Map the provider's subscription statuses (e.g., `active`, `past_due`, `canceled`) accurately to the SaaS platform's internal state machine.
-- **Testing**: Use sandbox/test environments provided by the gateways and simulate webhooks using CLI tools (like Stripe CLI) during development.
-
-### Implementation Checklist
-- [ ] Create a dedicated Webhook endpoint (e.g., `/api/webhooks/stripe`).
-- [ ] Use raw request body for signature verification (do not parse JSON before verification).
-- [ ] Ensure idempotency by tracking processed event IDs in the database.
-- [ ] Update local user/subscription state transactionally upon success.
-- [ ] Handle asynchronous failures with a dead-letter queue or retry mechanism.
-
-### Example: Stripe Webhook Signature Verification (Next.js App Router)
-```typescript
-import Stripe from 'stripe';
-import { headers } from 'next/headers';
-
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
-
-export async function POST(req: Request) {
-  const body = await req.text(); // Raw body required for signature
-  const signature = headers().get('Stripe-Signature') as string;
-
-  let event: Stripe.Event;
-
-  try {
-    event = stripe.webhooks.constructEvent(
-      body,
-      signature,
-      process.env.STRIPE_WEBHOOK_SECRET!
-    );
-  } catch (err: any) {
-    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
-  }
-
-  // Handle the event
-  if (event.type === 'checkout.session.completed') {
-    // Process successful payment, check idempotency, update DB
-  }
-
-  return new Response(JSON.stringify({ received: true }), { status: 200 });
-}
-```
-
-## Orchestration & Integration
-- Integrates with: `saas-billing`, `doku-payment-gateway`, `saas-mvp-launcher`.
-
-### Trigger Conditions
-Active whenever the user is working on billing integration, payment checkout, webhook handling, or integrating platforms like PayPal, Stripe, Xendit, Midtrans, or DOKU.
-
----
-
-<a name="bahasa-indonesia"></a>
-## Bahasa Indonesia
-
-### Deskripsi
-Panduan ahli untuk mengintegrasikan payment gateway utama (Stripe, PayPal, Xendit, Midtrans, DOKU) ke platform SaaS modern. Mencakup alur checkout, penanganan webhook yang aman, manajemen langganan, dan sinkronisasi dengan database lokal.
-
-### Instruksi
-- **Keamanan Utama**: Selalu validasi signature webhook sebelum memproses event pembayaran apa pun. Jangan pernah mempercayai data dari sisi klien untuk harga atau status pembayaran. Untuk DOKU, pastikan komponen signature (seperti request target) disusun secara ketat sesuai dokumentasi.
-- **Idempotensi**: Implementasikan kunci idempotensi (idempotency keys) untuk semua permintaan pembuatan pembayaran untuk menghindari tagihan ganda. Handler webhook juga harus idempoten. Untuk DOKU, sertakan header `Request-Id` unik.
-- **Sinkronisasi State**: Pastikan database lokal (misal: PostgreSQL, Supabase) diperbarui secara langsung dan transaksional saat menerima event webhook yang berhasil.
-- **Manajemen Langganan**: Petakan status langganan dari provider (misal: `active`, `past_due`, `canceled`) secara akurat ke state machine internal platform SaaS.
-- **Pengujian**: Gunakan lingkungan sandbox/test yang disediakan oleh gateway dan simulasikan webhook menggunakan tool CLI (seperti Stripe CLI) selama pengembangan.
-
-### Checklist Implementasi
-- [ ] Buat endpoint Webhook khusus (misal: `/api/webhooks/stripe`).
-- [ ] Gunakan raw request body untuk verifikasi signature (jangan parse JSON sebelum verifikasi).
-- [ ] Pastikan idempotensi dengan melacak ID event yang sudah diproses di database.
-- [ ] Perbarui state langganan/pengguna lokal secara transaksional saat sukses.
-- [ ] Tangani kegagalan asinkron dengan dead-letter queue atau mekanisme retry.
-
-### Contoh: Verifikasi Signature Webhook Stripe (Next.js App Router)
-```typescript
-import Stripe from 'stripe';
-import { headers } from 'next/headers';
-
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
-
-export async function POST(req: Request) {
-  const body = await req.text(); // Raw body dibutuhkan untuk signature
-  const signature = headers().get('Stripe-Signature') as string;
-
-  let event: Stripe.Event;
-
-  try {
-    event = stripe.webhooks.constructEvent(
-      body,
-      signature,
-      process.env.STRIPE_WEBHOOK_SECRET!
-    );
-  } catch (err: any) {
-    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
-  }
-
-  // Tangani event
-  if (event.type === 'checkout.session.completed') {
-    // Proses pembayaran sukses, cek idempotensi, update DB
-  }
-
-  return new Response(JSON.stringify({ received: true }), { status: 200 });
-}
-```
-
-## Integrasi Orkestrasi
-- Terintegrasi dengan: `saas-billing`, `doku-payment-gateway`, `saas-mvp-launcher`.
-
-### Kondisi Pemicu
-Aktif setiap kali pengguna sedang mengerjakan integrasi billing, checkout pembayaran, penanganan webhook, atau mengintegrasikan platform seperti PayPal, Stripe, Xendit, Midtrans, atau DOKU.
+version: "4.0.0"
+---
+
+# Payment Gateway Expert / Ahli Payment Gateway
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Expert guide for integrating major payment gateways (Stripe, PayPal, Xendit, Midtrans, DOKU SNAP BI) into modern SaaS platforms. Covers checkout flows, secure raw-body webhook handling, atomic idempotency to prevent race conditions, subscription state machines, and local database synchronization.
+
+### Core Principles
+- **Security First**: Always validate webhook signatures using the raw, unparsed request body before processing any payment event. Never trust client-side data for prices or payment status. For Indonesian gateways (DOKU, Midtrans, Xendit), strictly enforce the **SNAP BI standard (HMAC-SHA512)** and ISO8601 UTC/WIB timestamps.
+- **Idempotency & Race Condition Prevention**: Implement idempotency keys for all payment creation requests. For webhook ingestion, **DO NOT rely solely on `findUnique` checks**, as concurrent webhook retries cause race conditions. Always use **Atomic Updates** (`UPDATE ... WHERE status = 'PENDING'`) or database pessimistic locks (`SELECT ... FOR UPDATE`).
+- **Raw Body Ingestion**: Webhook signature verification fails if JSON is parsed or re-serialized with modified key ordering. Extract the exact raw string buffer (`req.text()` in Fetch API or `express.raw({ type: 'application/json' })` in Express).
+- **Early 200 OK Acknowledgment**: If a webhook event is verified but already processed, immediately return `200 OK` so the payment gateway halts retries.
+- **State Synchronization**: Ensure the local database (e.g., PostgreSQL, Supabase via Drizzle/Prisma) is updated transactionally upon receiving successful webhook events.
+- **Subscription Management**: Map provider subscription statuses (`trialing`, `active`, `past_due`, `canceled`) accurately to internal SaaS state machines.
+
+### Implementation Checklist
+- [ ] Create dedicated raw Webhook endpoint (e.g., `/api/webhooks/stripe`, `/api/webhooks/doku`).
+- [ ] Use raw request body string for signature verification (never parsed JSON).
+- [ ] Verify signature using proper algorithm (HMAC-SHA256 for Stripe/PayPal; HMAC-SHA512 for SNAP BI).
+- [ ] Implement Atomic Update idempotency (`WHERE status = 'PENDING'`) to eliminate race conditions.
+- [ ] Acknowledge duplicate webhooks immediately with HTTP `200 OK`.
+- [ ] Offload heavy post-payment operations (invoicing, emails, webhooks) to background job queues (BullMQ/Temporal).
+
+### Example: SNAP BI Webhook & Atomic Idempotency (Next.js App Router)
+```typescript
+import { headers } from 'next/headers';
+import crypto from 'crypto';
+import { db } from '@/lib/db';
+
+export async function POST(req: Request) {
+  const rawBody = await req.text(); // Raw body is mandatory
+  const headerList = await headers();
+  
+  const timestamp = headerList.get('x-timestamp') || '';
+  const receivedSig = headerList.get('x-signature') || '';
+  const authHeader = headerList.get('authorization') || '';
+  const token = authHeader.replace(/^Bearer\s+/i, '');
+  const path = new URL(req.url).pathname;
+
+  // 1. SNAP BI Body Hash & Signature Verification (HMAC-SHA512)
+  const bodyHash = crypto.createHash('sha256').update(rawBody, 'utf8').digest('hex').toLowerCase();
+  const stringToSign = `POST:${path}:${token}:${bodyHash}:${timestamp}`;
+  const calculatedSig = crypto
+    .createHmac('sha512', process.env.DOKU_SECRET_KEY!)
+    .update(stringToSign, 'utf8')
+    .digest('base64');
+
+  const isValid = crypto.timingSafeEqual(Buffer.from(receivedSig), Buffer.from(calculatedSig));
+  if (!isValid) {
+    return new Response('Invalid Signature', { status: 401 });
+  }
+
+  const payload = JSON.parse(rawBody);
+  const invoiceNumber = payload.order?.invoice_number;
+
+  // 2. Atomic Update: Eliminates Race Conditions by locking on 'PENDING' status
+  const updated = await db.transaction.updateMany({
+    where: {
+      invoiceNumber: invoiceNumber,
+      status: 'PENDING', // Key race condition prevention gate
+    },
+    data: {
+      status: 'PAID',
+      paidAt: new Date(),
+      externalReference: payload.transaction?.original_reference_no,
+    },
+  });
+
+  // 3. Duplicate Webhook Handling (Idempotency)
+  if (updated.count === 0) {
+    // Already processed or invalid invoice — return 200 to halt gateway retry spam
+    return new Response(JSON.stringify({ status: 'ALREADY_PROCESSED' }), { status: 200 });
+  }
+
+  // 4. Fulfillment (Execute only once)
+  await grantUserSubscription(invoiceNumber);
+
+  return new Response(JSON.stringify({ status: 'SUCCESS' }), { status: 200 });
+}
+
+async function grantUserSubscription(invoiceNumber: string) {
+  // Safe business logic execution
+}
+```
+
+## Orchestration & Integration
+- Integrates with: `saas-billing`, `doku-payment-gateway`, `doku-mcp-server`, `async-queue-temporal-expert`, `database-orm-expert`.
+
+### Trigger Conditions
+Active whenever the user is working on billing integration, payment checkout, webhook handling, or integrating platforms like PayPal, Stripe, Xendit, Midtrans, or DOKU SNAP BI.
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Panduan ahli untuk mengintegrasikan payment gateway utama (Stripe, PayPal, Xendit, Midtrans, DOKU SNAP BI) ke platform SaaS modern. Mencakup alur checkout, penanganan webhook raw-body aman, pencegahan race condition melalui atomic update, state machine langganan, dan sinkronisasi database lokal.
+
+### Prinsip Utama
+- **Keamanan Utama**: Selalu validasi signature webhook menggunakan *raw request body* murni sebelum memproses event pembayaran. Jangan pernah mempercayai data dari sisi klien untuk harga atau status pembayaran. Untuk gateway Indonesia (DOKU, Midtrans, Xendit), terapkan **standar SNAP BI (HMAC-SHA512)** dan format timestamp ISO8601.
+- **Idempotensi & Pencegahan Race Condition**: Implementasikan kunci idempotensi untuk semua pembuatan pembayaran. Pada penerimaan webhook, **JANGAN hanya mengandalkan pengecekan `findUnique`**, karena panggilan webhook paralel dari gateway dapat memicu race condition. Selalu gunakan **Atomic Update** (`UPDATE ... WHERE status = 'PENDING'`) atau database lock (`SELECT ... FOR UPDATE`).
+- **Raw Body Webhook**: Verifikasi tanda tangan akan gagal jika JSON di-parse atau di-serialize ulang karena perubahan urutan key atau spasi. Ambil buffer teks mentah (`req.text()` pada Fetch API atau `express.raw({ type: 'application/json' })` di Express).
+- **Balasan Cepat 200 OK**: Jika signature valid namun transaksi sudah berstatus lunas (webhook duplikat/retry), segera kembalikan HTTP `200 OK` agar payment gateway berhenti mengirimkan retry.
+- **Sinkronisasi State**: Pastikan database lokal (PostgreSQL/Supabase via Drizzle/Prisma) diperbarui secara transaksional saat menerima webhook sukses.
+- **Manajemen Langganan**: Petakan status langganan dari provider (`trialing`, `active`, `past_due`, `canceled`) secara akurat ke state machine internal SaaS.
+
+### Checklist Implementasi
+- [ ] Buat endpoint Webhook raw khusus (misal: `/api/webhooks/stripe`, `/api/webhooks/doku`).
+- [ ] Gunakan raw request body string untuk verifikasi signature (jangan parse JSON sebelum verifikasi).
+- [ ] Verifikasi signature dengan algoritma yang tepat (HMAC-SHA256 untuk Stripe/PayPal; HMAC-SHA512 untuk SNAP BI).
+- [ ] Terapkan Atomic Update (`WHERE status = 'PENDING'`) untuk mematikan peluang race condition.
+- [ ] Balas webhook duplikat secara instan dengan HTTP `200 OK`.
+- [ ] Lemparkan proses berat pasca-bayar (pembuatan invoice PDF, email, push notification) ke antrean latar belakang (BullMQ/Temporal).
+
+## Integrasi Orkestrasi
+- Terintegrasi dengan: `saas-billing`, `doku-payment-gateway`, `doku-mcp-server`, `async-queue-temporal-expert`, `database-orm-expert`.
+
+### Kondisi Pemicu
+Aktif setiap kali pengguna sedang mengerjakan integrasi billing, checkout pembayaran, penanganan webhook, atau mengintegrasikan platform seperti PayPal, Stripe, Xendit, Midtrans, atau DOKU SNAP BI.