vibes-plug 1.0.0

package/skills/saas-transformer/references/billing_integration_guide.md

@@ -0,0 +1,401 @@
+# Billing & Payment Gateway Integration Guide
+
+A comprehensive guide to setting up subscription billing, payment gateways, and Merchant of Record (MoR) systems. This guide covers Stripe, Midtrans, PayPal, Paddle, and FastSpring, detailing database structures and webhook verification in a multi-tenant SaaS application.
+
+---
+
+## 1. Gateway Type: Payment Gateway vs. Merchant of Record (MoR)
+
+Before choosing a billing system, it is vital to understand the two main categories of billing platforms:
+
+| Feature | Payment Gateway (Stripe, Midtrans, PayPal) | Merchant of Record (Paddle, FastSpring) |
+|---|---|---|
+| **Definition** | Processes payments but places legal/financial responsibilities on you. | Acts as the reseller of your software; handles transactions and compliance. |
+| **Sales Tax / VAT** | You must calculate, collect, and file taxes globally (using tools like Stripe Tax). | Automatically handles global taxes, compliance, and invoicing. |
+| **Chargeback Liability**| You manage chargeback disputes directly. | The MoR platform handles chargeback disputes. |
+| **Integration Complexity**| Highly customizable APIs, but requires more backend logic for compliance. | Simple to configure; checkout UI is managed by the MoR. |
+
+---
+
+## 2. Generic Multi-Gateway Database Schema
+
+To support multiple payment gateways, use a generic subscription schema.
+
+### Prisma Schema (`prisma/schema.prisma`)
+```prisma
+model Subscription {
+  id                 String   @id @default(cuid())
+  workspaceId        String   @unique
+  workspace          Workspace @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+  gateway            String   // "stripe", "midtrans", "paypal", "paddle", "fastspring"
+  gatewayCustomerId  String?  @unique
+  gatewaySubscriptionId String? @unique
+  gatewayPriceId     String?
+  status             String   // "active", "trialing", "past_due", "canceled", "unpaid"
+  currentPeriodEnd   DateTime
+  cancelAtPeriodEnd  Boolean  @default(false)
+  createdAt          DateTime @default(now())
+  updatedAt          DateTime @updatedAt
+}
+```
+
+### Drizzle ORM Schema (`lib/db/schema.ts`)
+```typescript
+import { pgTable, text, timestamp, boolean } from 'drizzle-orm/pg-core';
+
+export const subscriptions = pgTable('subscriptions', {
+  id: text('id').primaryKey(),
+  workspaceId: text('workspace_id').notNull().unique(),
+  gateway: text('gateway').notNull(), // "stripe", "midtrans", "paypal", "paddle", "fastspring"
+  gatewayCustomerId: text('gateway_customer_id').unique(),
+  gatewaySubscriptionId: text('gateway_subscription_id').unique(),
+  gatewayPriceId: text('gateway_price_id'),
+  status: text('status').notNull(),
+  currentPeriodEnd: timestamp('current_period_end').notNull(),
+  cancelAtPeriodEnd: boolean('cancel_at_period_end').default(false).notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});
+```
+
+---
+
+## 3. Webhook Implementations
+
+Webhooks are crucial to keep your SaaS database in sync with payment updates. Below are the implementation templates for Next.js 15 (App Router).
+
+### A. Stripe Integration
+Processes subscriptions and invoices. Verified via the Stripe SDK.
+
+```typescript
+import { NextResponse } from 'next/server';
+import Stripe from 'stripe';
+import { db } from '@/lib/db';
+import { subscriptions } from '@/lib/db/schema';
+import { eq } from 'drizzle-orm';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: '2025-01-01' as any });
+
+export async function POST(req: Request) {
+  const body = await req.text();
+  const signature = req.headers.get('Stripe-Signature')!;
+
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+  } catch (err: any) {
+    return NextResponse.json({ error: `Signature verification failed: ${err.message}` }, { status: 400 });
+  }
+
+  switch (event.type) {
+    case 'checkout.session.completed': {
+      const session = event.data.object as Stripe.Checkout.Session;
+      const workspaceId = session.metadata?.workspaceId;
+      if (!workspaceId) break;
+
+      const subscription = await stripe.subscriptions.retrieve(session.subscription as string);
+      await db.insert(subscriptions).values({
+        id: subscription.id,
+        workspaceId,
+        gateway: 'stripe',
+        gatewayCustomerId: session.customer as string,
+        gatewaySubscriptionId: subscription.id,
+        gatewayPriceId: subscription.items.data[0].price.id,
+        status: subscription.status,
+        currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+      });
+      break;
+    }
+    case 'invoice.payment_succeeded': {
+      const invoice = event.data.object as Stripe.Invoice;
+      if (!invoice.subscription) break;
+      const subscription = await stripe.subscriptions.retrieve(invoice.subscription as string);
+      await db.update(subscriptions)
+        .set({
+          status: subscription.status,
+          currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+        })
+        .where(eq(subscriptions.gatewaySubscriptionId, subscription.id));
+      break;
+    }
+    case 'customer.subscription.deleted': {
+      const subscription = event.data.object as Stripe.Subscription;
+      await db.update(subscriptions)
+        .set({ status: 'canceled' })
+        .where(eq(subscriptions.gatewaySubscriptionId, subscription.id));
+      break;
+    }
+  }
+  return NextResponse.json({ received: true });
+}
+```
+
+### B. Midtrans Integration
+Southeast Asia's popular payment gateway. Verified via SHA512 signature key matching.
+
+```typescript
+import { NextResponse } from 'next/server';
+import crypto from 'crypto';
+import { db } from '@/lib/db';
+import { subscriptions } from '@/lib/db/schema';
+import { eq } from 'drizzle-orm';
+
+export async function POST(req: Request) {
+  const body = await req.json();
+  const { order_id, status_code, gross_amount, signature_key, transaction_status, fraud_status } = body;
+
+  // Verify signature key: sha512(order_id + status_code + gross_amount + server_key)
+  const serverKey = process.env.MIDTRANS_SERVER_KEY!;
+  const hashed = crypto
+    .createHash('sha512')
+    .update(order_id + status_code + gross_amount + serverKey)
+    .digest('hex');
+
+  if (hashed !== signature_key) {
+    return NextResponse.json({ error: 'Invalid Midtrans signature' }, { status: 400 });
+  }
+
+  // Update subscription/payment state based on transaction_status
+  if (transaction_status === 'capture' || transaction_status === 'settlement') {
+    if (fraud_status === 'challenge') {
+      await db.update(subscriptions).set({ status: 'unpaid' }).where(eq(subscriptions.id, order_id));
+    } else {
+      await db.update(subscriptions)
+        .set({ status: 'active', currentPeriodEnd: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000) })
+        .where(eq(subscriptions.id, order_id));
+    }
+  } else if (['cancel', 'deny', 'expire'].includes(transaction_status)) {
+    await db.update(subscriptions).set({ status: 'canceled' }).where(eq(subscriptions.id, order_id));
+  } else if (transaction_status === 'pending') {
+    await db.update(subscriptions).set({ status: 'unpaid' }).where(eq(subscriptions.id, order_id));
+  }
+
+  return NextResponse.json({ success: true });
+}
+```
+
+### C. PayPal Integration
+Global subscription billing. Verified via PayPal API request validation.
+
+```typescript
+import { NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { subscriptions } from '@/lib/db/schema';
+import { eq } from 'drizzle-orm';
+
+async function verifyPayPalSignature(headers: Headers, rawBody: string, webhookId: string) {
+  // Call PayPal API to verify signature authenticity
+  const endpoint = process.env.PAYPAL_MODE === 'live' 
+    ? 'https://api-m.paypal.com' 
+    : 'https://api-m.sandbox.paypal.com';
+
+  const authHeader = headers.get('authorization');
+  if (!authHeader) return false;
+
+  const response = await fetch(`${endpoint}/v1/notifications/verify-webhook-signature`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': authHeader,
+    },
+    body: JSON.stringify({
+      auth_algo: headers.get('paypal-auth-algo'),
+      cert_url: headers.get('paypal-cert-url'),
+      transmission_id: headers.get('paypal-transmission-id'),
+      transmission_sig: headers.get('paypal-transmission-sig'),
+      transmission_time: headers.get('paypal-transmission-time'),
+      webhook_id: webhookId,
+      webhook_event: JSON.parse(rawBody),
+    }),
+  });
+
+  const verification = await response.json();
+  return verification.verification_status === 'SUCCESS';
+}
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const webhookId = process.env.PAYPAL_WEBHOOK_ID!;
+
+  const isValid = await verifyPayPalSignature(req.headers, rawBody, webhookId);
+  if (!isValid) {
+    return NextResponse.json({ error: 'PayPal signature invalid' }, { status: 400 });
+  }
+
+  const event = JSON.parse(rawBody);
+
+  switch (event.event_type) {
+    case 'BILLING.SUBSCRIPTION.CREATED': {
+      const sub = event.resource;
+      const workspaceId = sub.custom_id; // Pass workspace ID in custom_id
+      if (!workspaceId) break;
+
+      await db.insert(subscriptions).values({
+        id: sub.id,
+        workspaceId,
+        gateway: 'paypal',
+        gatewayCustomerId: sub.subscriber.payer_id,
+        gatewaySubscriptionId: sub.id,
+        gatewayPriceId: sub.plan_id,
+        status: 'active',
+        currentPeriodEnd: new Date(sub.billing_info.next_billing_time),
+      });
+      break;
+    }
+    case 'BILLING.SUBSCRIPTION.CANCELLED': {
+      const sub = event.resource;
+      await db.update(subscriptions)
+        .set({ status: 'canceled' })
+        .where(eq(subscriptions.gatewaySubscriptionId, sub.id));
+      break;
+    }
+  }
+
+  return NextResponse.json({ received: true });
+}
+```
+
+### D. Paddle Integration (Paddle Billing v2)
+Merchant of Record. Verified locally using an HMAC-SHA256 signature key verification.
+
+```typescript
+import { NextResponse } from 'next/server';
+import crypto from 'crypto';
+import { db } from '@/lib/db';
+import { subscriptions } from '@/lib/db/schema';
+import { eq } from 'drizzle-orm';
+
+function verifyPaddleSignature(body: string, signatureHeader: string, secret: string): boolean {
+  const parts = signatureHeader.split(';');
+  const tsPart = parts.find(p => p.startsWith('ts='));
+  const h1Part = parts.find(p => p.startsWith('h1='));
+  if (!tsPart || !h1Part) return false;
+
+  const ts = tsPart.split('=')[1];
+  const h1 = h1Part.split('=')[1];
+
+  const payload = `${ts}:${body}`;
+  const computedHash = crypto.createHmac('sha256', secret).update(payload).digest('hex');
+  return computedHash === h1;
+}
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const signature = req.headers.get('Paddle-Signature')!;
+  const secret = process.env.PADDLE_WEBHOOK_SECRET!;
+
+  if (!verifyPaddleSignature(rawBody, signature, secret)) {
+    return NextResponse.json({ error: 'Invalid Paddle signature' }, { status: 400 });
+  }
+
+  const event = JSON.parse(rawBody);
+  const eventType = event.event_type;
+  const data = event.data;
+
+  switch (eventType) {
+    case 'subscription.created':
+    case 'subscription.updated': {
+      const workspaceId = data.custom_data?.workspaceId;
+      if (!workspaceId) break;
+
+      await db.insert(subscriptions).values({
+        id: data.id,
+        workspaceId,
+        gateway: 'paddle',
+        gatewayCustomerId: data.customer_id,
+        gatewaySubscriptionId: data.id,
+        gatewayPriceId: data.items[0].price.id,
+        status: data.status, // active, trialing, paused
+        currentPeriodEnd: new Date(data.current_billing_period.ends_at),
+      }).onConflictDoUpdate({
+        target: subscriptions.workspaceId,
+        set: {
+          status: data.status,
+          currentPeriodEnd: new Date(data.current_billing_period.ends_at),
+          gatewayPriceId: data.items[0].price.id,
+        }
+      });
+      break;
+    }
+    case 'subscription.canceled': {
+      await db.update(subscriptions)
+        .set({ status: 'canceled' })
+        .where(eq(subscriptions.gatewaySubscriptionId, data.id));
+      break;
+    }
+  }
+
+  return NextResponse.json({ received: true });
+}
+```
+
+### E. FastSpring Integration
+Merchant of Record. Verified via an HMAC-SHA256 signature key verification.
+
+```typescript
+import { NextResponse } from 'next/server';
+import crypto from 'crypto';
+import { db } from '@/lib/db';
+import { subscriptions } from '@/lib/db/schema';
+import { eq } from 'drizzle-orm';
+
+function verifyFastSpringSignature(body: string, signature: string, secretKey: string): boolean {
+  const hash = crypto.createHmac('sha256', secretKey).update(body).digest('base64');
+  return hash === signature;
+}
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const signature = req.headers.get('X-FS-Signature')!;
+  const secretKey = process.env.FASTSPRING_SHARED_SECRET!;
+
+  if (!verifyFastSpringSignature(rawBody, signature, secretKey)) {
+    return NextResponse.json({ error: 'Invalid FastSpring signature' }, { status: 400 });
+  }
+
+  const payload = JSON.parse(rawBody);
+
+  for (const event of payload.events) {
+    switch (event.type) {
+      case 'subscription.activated': {
+        const sub = event.data;
+        const workspaceId = sub.tags?.workspaceId;
+        if (!workspaceId) break;
+
+        await db.insert(subscriptions).values({
+          id: sub.id,
+          workspaceId,
+          gateway: 'fastspring',
+          gatewayCustomerId: sub.account,
+          gatewaySubscriptionId: sub.id,
+          gatewayPriceId: sub.product,
+          status: 'active',
+          currentPeriodEnd: new Date(sub.nextSession),
+        });
+        break;
+      }
+      case 'subscription.canceled': {
+        const sub = event.data;
+        await db.update(subscriptions)
+          .set({ status: 'canceled' })
+          .where(eq(subscriptions.gatewaySubscriptionId, sub.id));
+        break;
+      }
+    }
+  }
+
+  return NextResponse.json({ received: true });
+}
+```
+
+---
+
+## 4. Best Practices for Webhook Handlers
+
+1. **Webhook Idempotency**: Payment gateways can redeliver webhooks. Always store a list of processed event IDs in your database to prevent duplicate actions:
+   ```typescript
+   const processed = await db.query.processedEvents.findFirst({ where: eq(processedEvents.id, eventId) });
+   if (processed) return NextResponse.json({ received: true });
+   ```
+2. **Handle Async Work Gracefully**: Send a fast response (`200 OK`) back to the gateway first, then process any heavy logic asynchronously (or via queue systems like BullMQ) if necessary, to avoid gateway timeouts.
+3. **Database Locks**: Run your update queries inside clean transactions to avoid concurrency anomalies.

package/skills/saas-transformer/references/feature_gating_patterns.md

@@ -0,0 +1,137 @@
+# Feature Gating & Usage Limits Patterns
+
+Standard patterns for restricting access to features and enforcing quotas based on plan configurations.
+
+---
+
+## 1. Feature Map Definitions
+
+Define a clear schema mapping plans to features and usage limits.
+
+```typescript
+export interface PlanConfig {
+  name: string;
+  maxMembers: number;
+  maxProjects: number;
+  features: {
+    advancedReporting: boolean;
+    apiAccess: boolean;
+    customDomain: boolean;
+  };
+}
+
+export const PLAN_CONFIGS: Record<string, PlanConfig> = {
+  free: {
+    name: 'Free',
+    maxMembers: 1,
+    maxProjects: 3,
+    features: {
+      advancedReporting: false,
+      apiAccess: false,
+      customDomain: false
+    }
+  },
+  pro: {
+    name: 'Professional',
+    maxMembers: 10,
+    maxProjects: 50,
+    features: {
+      advancedReporting: true,
+      apiAccess: true,
+      customDomain: false
+    }
+  },
+  enterprise: {
+    name: 'Enterprise',
+    maxMembers: 100,
+    maxProjects: 999999,
+    features: {
+      advancedReporting: true,
+      apiAccess: true,
+      customDomain: true
+    }
+  }
+};
+```
+
+---
+
+## 2. Server-side Gate Keepers (Next.js Actions / Routes)
+
+Implement standard assertions in your data access layer.
+
+```typescript
+import { getWorkspaceSubscription } from './billing';
+import { PLAN_CONFIGS } from './plan-configs';
+import { db } from './db';
+import { projects } from './db/schema';
+import { count, eq } from 'drizzle-orm';
+
+// Feature gate assertion
+export async function assertHasFeature(workspaceId: string, feature: keyof PlanConfig['features']) {
+  const { plan, isActive } = await getWorkspaceSubscription(workspaceId);
+  const activePlan = isActive ? plan : 'free';
+  
+  const hasFeature = PLAN_CONFIGS[activePlan]?.features[feature];
+  if (!hasFeature) {
+    throw new Error(`Your plan (${activePlan}) does not support the feature: ${feature}`);
+  }
+}
+
+// Usage limits assertion
+export async function assertWithinProjectLimit(workspaceId: string) {
+  const { plan, isActive } = await getWorkspaceSubscription(workspaceId);
+  const activePlan = isActive ? plan : 'free';
+  
+  const limit = PLAN_CONFIGS[activePlan].maxProjects;
+  
+  const [projectCount] = await db
+    .select({ val: count() })
+    .from(projects)
+    .where(eq(projects.workspaceId, workspaceId));
+
+  if (projectCount.val >= limit) {
+    throw new Error(`Project limit reached (${projectCount.val}/${limit}). Please upgrade your plan.`);
+  }
+}
+```
+
+---
+
+## 3. UI Graceful Degradation / Upgrade Banner
+
+Wrap component gates clean in React to encourage high conversion paths.
+
+```tsx
+import React from 'react';
+import { Button } from '@/components/ui/button';
+
+interface UpgradeGuardProps {
+  hasFeature: boolean;
+  featureName: string;
+  children: React.ReactNode;
+}
+
+export function UpgradeGuard({ hasFeature, featureName, children }: UpgradeGuardProps) {
+  if (hasFeature) {
+    return <>{children}</>;
+  }
+
+  return (
+    <div className="relative border border-dashed border-gray-300 rounded-lg p-8 text-center bg-gray-50/50">
+      <div className="absolute inset-0 bg-white/40 backdrop-blur-[1px] rounded-lg" />
+      <div className="relative z-10 max-w-sm mx-auto">
+        <h3 className="text-lg font-semibold text-gray-900">Unlock {featureName}</h3>
+        <p className="mt-2 text-sm text-gray-500">
+          This feature is available on our Professional and Enterprise plans. Upgrade today to scale.
+        </p>
+        <div className="mt-4">
+          <Button href="/settings/billing" variant="default">
+            View Pricing Plans
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```

package/skills/saas-transformer/references/saas_transformation_checklist.md

@@ -0,0 +1,121 @@
+# SaaS Transformation Checklist
+
+Detailed verification checkpoints and implementation patterns for converting a single-tenant application to a multi-tenant SaaS platform.
+
+---
+
+## Phase 1: Discovery & Analysis
+
+- [ ] **Data Model Mapping**: Extract all relationships. Identify which tables are "global" (shared reference data, e.g., plan configurations, country list) and which are "tenant-specific" (user data, posts, transactions).
+- [ ] **Auth Audit**: Check if the app uses native session storage, custom cookies, or third-party auth. Identify where users are created and stored.
+- [ ] **API Access Points**: Audit all public and internal route files. Note down endpoints that lack authentication.
+- [ ] **Pricing Strategy Fit**: Document the exact plan rules.
+  - *Example*: Free Plan has 1 project limit. Pro Plan has unlimited projects.
+
+---
+
+## Phase 2: Multi-Tenancy Foundation
+
+### PostgreSQL Row-Level Security (RLS) Pattern
+When using a shared-schema model, configure your tables to automatically isolate data.
+
+```sql
+-- 1. Enable RLS
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;
+
+-- 2. Create helper function to retrieve current tenant from session context
+CREATE OR REPLACE FUNCTION auth.current_tenant_id()
+RETURNS UUID AS $$
+  SELECT NULLIF(current_setting('app.current_tenant_id', true), '')::UUID;
+$$ LANGUAGE sql STABLE;
+
+-- 3. Apply policies using membership lookup
+CREATE POLICY tenant_isolation_policy ON projects
+  AS RESTRICTIVE
+  USING (
+    workspace_id = auth.current_tenant_id()
+  );
+```
+
+### Middleware Connection Context Setting (Node.js/Express Example)
+Ensure every database transaction or connection sets the `app.current_tenant_id` session configuration.
+
+```typescript
+import { Request, Response, NextFunction } from 'express';
+import { db } from '../lib/db';
+
+export async function tenantMiddleware(req: Request, res: Response, next: NextFunction) {
+  const tenantId = req.headers['x-tenant-id'] || req.user?.workspaceId;
+  
+  if (!tenantId) {
+    return res.status(400).json({ error: 'Tenant context missing' });
+  }
+
+  // Inject session variable inside transaction wrapper or pool client
+  await db.execute(sql`SET LOCAL app.current_tenant_id = ${tenantId}`);
+  next();
+}
+```
+
+---
+
+## Phase 3: Authentication & Authorization
+
+- [ ] **Workspace Member Resolution**: Ensure a user is mapped to multiple workspaces via a join table (`workspace_members`).
+- [ ] **Role-Based Checkpoint**:
+  ```typescript
+  export function requireRole(allowedRoles: ('owner' | 'admin' | 'member')[]) {
+    return (req: Request, res: Response, next: NextFunction) => {
+      const userRole = req.user?.role;
+      if (!userRole || !allowedRoles.includes(userRole)) {
+        return res.status(403).json({ error: 'Permission denied' });
+      }
+      next();
+    };
+  }
+  ```
+
+---
+
+## Phase 4: Billing & Subscription
+
+- [ ] **Stripe Event Handling Idempotency**: Save all processed Stripe Event IDs to a database log table to prevent processing webhooks twice.
+- [ ] **Dunning Flow**: Set up Stripe triggers for `invoice.payment_failed` to send a dynamic link allowing the user to update their payment card in one click.
+
+---
+
+## Phase 5: Workspace & Team Management
+
+- [ ] **Invitation Tokens**: Generate cryptographically secure invite tokens using standard library utilities:
+  ```typescript
+  import crypto from 'crypto';
+  const token = crypto.randomBytes(32).toString('hex');
+  ```
+- [ ] **Workspace Switcher Logic**: When changing workspaces, update the session token (or JWT) and redirect the user back to the application dashboard to force frontend hydration with new data.
+
+---
+
+## Phase 6: SaaS Frontend & Landing
+
+- [ ] **Responsive Navigation**: Use dynamic dashboard layouts that collapse sidebars on mobile touchpoints.
+- [ ] **SEO Configuration**: Output unique structured data per landing section.
+
+---
+
+## Phase 7: API Layer & Feature Gating
+
+- [ ] **Feature Flags**: Guard pages and controls using a hook pattern:
+  ```typescript
+  const { hasFeature } = useSubscription();
+  if (!hasFeature('advanced-export')) {
+    return <UpgradeBanner featureName="Advanced Export" />;
+  }
+  ```
+
+---
+
+## Phase 8: Production Hardening & Launch
+
+- [ ] **Rollback Runbook**: Create rollback scripts for DB migrations.
+- [ ] **Cascade Deletion Tests**: Ensure deleting a workspace cleans up all child tables cleanly without foreign-key orphan exceptions.