specweave 0.24.0 → 0.24.1

package/plugins/specweave-payments/commands/subscription-manage.md

@@ -0,0 +1,386 @@
+# Subscription Management
+
+Generate complete subscription management system.
+
+## Task
+
+You are a subscription billing expert. Generate production-ready subscription management with billing, upgrades, and cancellations.
+
+### Steps:
+
+1. **Ask for Requirements**:
+   - Pricing tiers (Basic, Pro, Enterprise)
+   - Billing interval (monthly, annual)
+   - Features per tier
+   - Trial period
+
+2. **Generate Pricing Configuration**:
+
+```typescript
+// config/pricing.ts
+export const PRICING_PLANS = {
+  basic: {
+    id: 'basic',
+    name: 'Basic',
+    description: 'For individuals and small teams',
+    prices: {
+      monthly: {
+        amount: 9,
+        stripePriceId: 'price_basic_monthly',
+      },
+      annual: {
+        amount: 90,
+        stripePriceId: 'price_basic_annual',
+        savings: 18, // 2 months free
+      },
+    },
+    features: [
+      '10 projects',
+      '5 GB storage',
+      'Basic support',
+    ],
+    limits: {
+      projects: 10,
+      storage: 5 * 1024 * 1024 * 1024, // 5 GB in bytes
+      apiCallsPerMonth: 10000,
+    },
+  },
+  pro: {
+    id: 'pro',
+    name: 'Pro',
+    description: 'For growing teams',
+    prices: {
+      monthly: {
+        amount: 29,
+        stripePriceId: 'price_pro_monthly',
+      },
+      annual: {
+        amount: 290,
+        stripePriceId: 'price_pro_annual',
+        savings: 58,
+      },
+    },
+    features: [
+      'Unlimited projects',
+      '50 GB storage',
+      'Priority support',
+      'Advanced analytics',
+    ],
+    limits: {
+      projects: Infinity,
+      storage: 50 * 1024 * 1024 * 1024,
+      apiCallsPerMonth: 100000,
+    },
+  },
+  enterprise: {
+    id: 'enterprise',
+    name: 'Enterprise',
+    description: 'For large organizations',
+    prices: {
+      monthly: {
+        amount: 99,
+        stripePriceId: 'price_enterprise_monthly',
+      },
+      annual: {
+        amount: 990,
+        stripePriceId: 'price_enterprise_annual',
+        savings: 198,
+      },
+    },
+    features: [
+      'Unlimited everything',
+      '1 TB storage',
+      '24/7 dedicated support',
+      'Custom integrations',
+      'SLA guarantee',
+    ],
+    limits: {
+      projects: Infinity,
+      storage: 1024 * 1024 * 1024 * 1024,
+      apiCallsPerMonth: Infinity,
+    },
+  },
+};
+```
+
+3. **Generate Subscription Service**:
+
+```typescript
+// services/subscription.service.ts
+import Stripe from 'stripe';
+import { PRICING_PLANS } from '../config/pricing';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+export class SubscriptionService {
+  // Create subscription
+  async create(userId: string, planId: string, interval: 'monthly' | 'annual') {
+    const user = await db.users.findUnique({ where: { id: userId } });
+    const plan = PRICING_PLANS[planId];
+
+    if (!plan) throw new Error('Invalid plan');
+
+    // Create Stripe customer if doesn't exist
+    let customerId = user.stripeCustomerId;
+    if (!customerId) {
+      const customer = await stripe.customers.create({
+        email: user.email,
+        metadata: { userId },
+      });
+      customerId = customer.id;
+      await db.users.update({
+        where: { id: userId },
+        data: { stripeCustomerId: customerId },
+      });
+    }
+
+    // Create subscription
+    const subscription = await stripe.subscriptions.create({
+      customer: customerId,
+      items: [{ price: plan.prices[interval].stripePriceId }],
+      trial_period_days: 14, // 14-day trial
+      payment_behavior: 'default_incomplete',
+      payment_settings: {
+        save_default_payment_method: 'on_subscription',
+      },
+      expand: ['latest_invoice.payment_intent'],
+    });
+
+    // Save to database
+    await db.subscriptions.create({
+      data: {
+        userId,
+        stripeSubscriptionId: subscription.id,
+        stripePriceId: plan.prices[interval].stripePriceId,
+        status: subscription.status,
+        planId,
+        interval,
+        currentPeriodStart: new Date(subscription.current_period_start * 1000),
+        currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+        trialEnd: subscription.trial_end
+          ? new Date(subscription.trial_end * 1000)
+          : null,
+      },
+    });
+
+    return {
+      subscriptionId: subscription.id,
+      clientSecret: subscription.latest_invoice.payment_intent.client_secret,
+    };
+  }
+
+  // Upgrade/downgrade subscription
+  async changePlan(userId: string, newPlanId: string, newInterval: 'monthly' | 'annual') {
+    const subscription = await db.subscriptions.findFirst({
+      where: { userId, status: 'active' },
+    });
+
+    if (!subscription) throw new Error('No active subscription');
+
+    const newPlan = PRICING_PLANS[newPlanId];
+    const newPriceId = newPlan.prices[newInterval].stripePriceId;
+
+    // Update Stripe subscription
+    const stripeSubscription = await stripe.subscriptions.retrieve(
+      subscription.stripeSubscriptionId
+    );
+
+    const updatedSubscription = await stripe.subscriptions.update(
+      subscription.stripeSubscriptionId,
+      {
+        items: [
+          {
+            id: stripeSubscription.items.data[0].id,
+            price: newPriceId,
+          },
+        ],
+        proration_behavior: 'always_invoice', // Prorate charges
+      }
+    );
+
+    // Update database
+    await db.subscriptions.update({
+      where: { id: subscription.id },
+      data: {
+        stripePriceId: newPriceId,
+        planId: newPlanId,
+        interval: newInterval,
+      },
+    });
+
+    return updatedSubscription;
+  }
+
+  // Cancel subscription
+  async cancel(userId: string, cancelAtPeriodEnd = true) {
+    const subscription = await db.subscriptions.findFirst({
+      where: { userId, status: 'active' },
+    });
+
+    if (!subscription) throw new Error('No active subscription');
+
+    if (cancelAtPeriodEnd) {
+      // Cancel at end of billing period
+      await stripe.subscriptions.update(subscription.stripeSubscriptionId, {
+        cancel_at_period_end: true,
+      });
+
+      await db.subscriptions.update({
+        where: { id: subscription.id },
+        data: { cancelAtPeriodEnd: true },
+      });
+    } else {
+      // Cancel immediately
+      await stripe.subscriptions.cancel(subscription.stripeSubscriptionId);
+
+      await db.subscriptions.update({
+        where: { id: subscription.id },
+        data: { status: 'canceled', canceledAt: new Date() },
+      });
+    }
+  }
+
+  // Resume canceled subscription
+  async resume(userId: string) {
+    const subscription = await db.subscriptions.findFirst({
+      where: { userId, cancelAtPeriodEnd: true },
+    });
+
+    if (!subscription) throw new Error('No subscription to resume');
+
+    await stripe.subscriptions.update(subscription.stripeSubscriptionId, {
+      cancel_at_period_end: false,
+    });
+
+    await db.subscriptions.update({
+      where: { id: subscription.id },
+      data: { cancelAtPeriodEnd: false },
+    });
+  }
+
+  // Get subscription status
+  async getStatus(userId: string) {
+    const subscription = await db.subscriptions.findFirst({
+      where: { userId },
+      orderBy: { createdAt: 'desc' },
+    });
+
+    if (!subscription) return null;
+
+    const plan = PRICING_PLANS[subscription.planId];
+    return {
+      ...subscription,
+      plan,
+      isActive: subscription.status === 'active',
+      isTrialing: subscription.status === 'trialing',
+      isCanceling: subscription.cancelAtPeriodEnd,
+    };
+  }
+
+  // Check feature access
+  async canAccess(userId: string, feature: string, value?: number) {
+    const status = await this.getStatus(userId);
+
+    if (!status || !status.isActive) return false;
+
+    const limits = status.plan.limits;
+
+    // Check specific limits
+    switch (feature) {
+      case 'projects':
+        const projectCount = await db.projects.count({ where: { userId } });
+        return projectCount < limits.projects;
+
+      case 'storage':
+        const storageUsed = await this.getStorageUsage(userId);
+        return storageUsed < limits.storage;
+
+      case 'api_calls':
+        const apiCalls = await this.getApiCallsThisMonth(userId);
+        return apiCalls < limits.apiCallsPerMonth;
+
+      default:
+        return false;
+    }
+  }
+}
+```
+
+4. **Generate Usage Tracking**:
+
+```typescript
+// Track API usage for metered billing
+export class UsageTracker {
+  async recordApiCall(userId: string) {
+    const subscription = await db.subscriptions.findFirst({
+      where: { userId, status: 'active' },
+    });
+
+    if (!subscription) return;
+
+    // Increment usage
+    await db.usageRecords.create({
+      data: {
+        subscriptionId: subscription.id,
+        type: 'api_call',
+        quantity: 1,
+        timestamp: new Date(),
+      },
+    });
+
+    // Optional: Report to Stripe for metered billing
+    if (subscription.meteringEnabled) {
+      await stripe.subscriptionItems.createUsageRecord(
+        subscription.stripeSubscriptionItemId,
+        {
+          quantity: 1,
+          timestamp: Math.floor(Date.now() / 1000),
+        }
+      );
+    }
+  }
+
+  async getUsage(userId: string, period: 'month' | 'all' = 'month') {
+    const subscription = await db.subscriptions.findFirst({
+      where: { userId },
+    });
+
+    if (!subscription) return null;
+
+    const startDate =
+      period === 'month'
+        ? new Date(new Date().setDate(1)) // Start of month
+        : undefined;
+
+    const usage = await db.usageRecords.groupBy({
+      by: ['type'],
+      where: {
+        subscriptionId: subscription.id,
+        timestamp: startDate ? { gte: startDate } : undefined,
+      },
+      _sum: {
+        quantity: true,
+      },
+    });
+
+    return usage;
+  }
+}
+```
+
+### Best Practices Included:
+
+- Trial periods
+- Proration on plan changes
+- Cancel at period end vs immediate
+- Usage tracking for metered billing
+- Feature gating based on plan
+- Subscription resumption
+- Clear pricing configuration
+
+### Example Usage:
+
+```
+User: "Set up subscription with Basic, Pro, Enterprise tiers"
+Result: Complete subscription system with billing, upgrades, trials
+```

package/plugins/specweave-payments/commands/webhook-setup.md

@@ -0,0 +1,295 @@
+# Payment Webhook Configuration
+
+Generate secure webhook handlers for payment providers.
+
+## Task
+
+You are a payment webhook security expert. Generate secure, production-ready webhook handlers.
+
+### Steps:
+
+1. **Ask for Provider**:
+   - Stripe
+   - PayPal
+   - Square
+   - Custom payment gateway
+
+2. **Generate Webhook Endpoint** (Stripe):
+
+```typescript
+import crypto from 'crypto';
+import express from 'express';
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+const app = express();
+
+// CRITICAL: Use raw body for webhook signature verification
+app.post(
+  '/api/webhooks/stripe',
+  express.raw({ type: 'application/json' }),
+  async (req, res) => {
+    const sig = req.headers['stripe-signature'];
+    const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;
+
+    let event;
+
+    try {
+      // Verify webhook signature
+      event = stripe.webhooks.constructEvent(
+        req.body,
+        sig!,
+        webhookSecret
+      );
+    } catch (err) {
+      console.error(`Webhook signature verification failed: ${err.message}`);
+      return res.status(400).send(`Webhook Error: ${err.message}`);
+    }
+
+    // Handle event idempotently
+    const eventId = event.id;
+    const existingEvent = await db.webhookEvents.findUnique({
+      where: { stripeEventId: eventId },
+    });
+
+    if (existingEvent) {
+      console.log(`Duplicate webhook event: ${eventId}`);
+      return res.status(200).json({ received: true });
+    }
+
+    // Store event (prevents duplicate processing)
+    await db.webhookEvents.create({
+      data: {
+        stripeEventId: eventId,
+        type: event.type,
+        processedAt: new Date(),
+      },
+    });
+
+    // Process event in background to return 200 quickly
+    processWebhookEvent(event).catch((error) => {
+      console.error(`Failed to process webhook: ${error.message}`);
+      // Alert ops team
+    });
+
+    res.status(200).json({ received: true });
+  }
+);
+
+async function processWebhookEvent(event: Stripe.Event) {
+  switch (event.type) {
+    case 'checkout.session.completed':
+      await handleCheckoutComplete(event.data.object);
+      break;
+
+    case 'customer.subscription.created':
+    case 'customer.subscription.updated':
+      await handleSubscriptionChange(event.data.object);
+      break;
+
+    case 'customer.subscription.deleted':
+      await handleSubscriptionCanceled(event.data.object);
+      break;
+
+    case 'invoice.paid':
+      await handleInvoicePaid(event.data.object);
+      break;
+
+    case 'invoice.payment_failed':
+      await handleInvoicePaymentFailed(event.data.object);
+      break;
+
+    case 'payment_intent.succeeded':
+      await handlePaymentSuccess(event.data.object);
+      break;
+
+    case 'payment_intent.payment_failed':
+      await handlePaymentFailed(event.data.object);
+      break;
+
+    case 'charge.dispute.created':
+      await handleDisputeCreated(event.data.object);
+      break;
+
+    case 'customer.created':
+      await handleCustomerCreated(event.data.object);
+      break;
+
+    default:
+      console.log(`Unhandled event type: ${event.type}`);
+  }
+}
+```
+
+3. **Generate PayPal Webhook**:
+
+```typescript
+import crypto from 'crypto';
+
+app.post('/api/webhooks/paypal', express.json(), async (req, res) => {
+  const webhookId = process.env.PAYPAL_WEBHOOK_ID!;
+  const webhookEvent = req.body;
+
+  // Verify PayPal webhook signature
+  const isValid = await verifyPayPalWebhook(req, webhookId);
+
+  if (!isValid) {
+    return res.status(400).send('Invalid webhook signature');
+  }
+
+  const eventType = webhookEvent.event_type;
+
+  switch (eventType) {
+    case 'PAYMENT.CAPTURE.COMPLETED':
+      await handlePayPalPaymentCompleted(webhookEvent.resource);
+      break;
+
+    case 'BILLING.SUBSCRIPTION.CREATED':
+      await handlePayPalSubscriptionCreated(webhookEvent.resource);
+      break;
+
+    case 'BILLING.SUBSCRIPTION.CANCELLED':
+      await handlePayPalSubscriptionCancelled(webhookEvent.resource);
+      break;
+
+    default:
+      console.log(`Unhandled PayPal event: ${eventType}`);
+  }
+
+  res.status(200).json({ received: true });
+});
+
+async function verifyPayPalWebhook(req, webhookId) {
+  const transmissionId = req.headers['paypal-transmission-id'];
+  const timestamp = req.headers['paypal-transmission-time'];
+  const signature = req.headers['paypal-transmission-sig'];
+  const certUrl = req.headers['paypal-cert-url'];
+
+  const response = await fetch(
+    `https://api.paypal.com/v1/notifications/verify-webhook-signature`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${await getPayPalAccessToken()}`,
+      },
+      body: JSON.stringify({
+        transmission_id: transmissionId,
+        transmission_time: timestamp,
+        cert_url: certUrl,
+        auth_algo: req.headers['paypal-auth-algo'],
+        transmission_sig: signature,
+        webhook_id: webhookId,
+        webhook_event: req.body,
+      }),
+    }
+  );
+
+  const data = await response.json();
+  return data.verification_status === 'SUCCESS';
+}
+```
+
+4. **Generate Webhook Testing Script**:
+
+```typescript
+// test-webhook.ts
+import { exec } from 'child_process';
+import util from 'util';
+
+const execPromise = util.promisify(exec);
+
+async function testWebhook() {
+  // Install Stripe CLI: brew install stripe/stripe-cli/stripe
+
+  // Listen to webhooks
+  const { stdout } = await execPromise('stripe listen --forward-to localhost:3000/api/webhooks/stripe');
+  console.log(stdout);
+
+  // Trigger test events
+  await execPromise('stripe trigger payment_intent.succeeded');
+  await execPromise('stripe trigger customer.subscription.created');
+  await execPromise('stripe trigger invoice.payment_failed');
+}
+
+testWebhook();
+```
+
+5. **Generate Monitoring & Alerting**:
+
+```typescript
+// Monitor webhook failures
+async function monitorWebhooks() {
+  const failedEvents = await db.webhookEvents.findMany({
+    where: {
+      processed: false,
+      createdAt: {
+        lt: new Date(Date.now() - 5 * 60 * 1000), // 5 minutes ago
+      },
+    },
+  });
+
+  if (failedEvents.length > 0) {
+    await sendAlert({
+      type: 'webhook_failure',
+      count: failedEvents.length,
+      events: failedEvents.map((e) => e.type),
+    });
+  }
+}
+
+// Retry failed webhooks
+async function retryFailedWebhooks() {
+  const failedEvents = await db.webhookEvents.findMany({
+    where: { processed: false },
+    take: 10,
+  });
+
+  for (const event of failedEvents) {
+    try {
+      await processWebhookEvent(event.data);
+      await db.webhookEvents.update({
+        where: { id: event.id },
+        data: { processed: true, processedAt: new Date() },
+      });
+    } catch (error) {
+      console.error(`Retry failed for event ${event.id}: ${error.message}`);
+    }
+  }
+}
+```
+
+6. **Generate Webhook Schema** (Database):
+
+```sql
+CREATE TABLE webhook_events (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  stripe_event_id VARCHAR(255) UNIQUE NOT NULL,
+  type VARCHAR(100) NOT NULL,
+  data JSONB NOT NULL,
+  processed BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP DEFAULT NOW(),
+  processed_at TIMESTAMP
+);
+
+CREATE INDEX idx_webhook_events_type ON webhook_events(type);
+CREATE INDEX idx_webhook_events_processed ON webhook_events(processed);
+```
+
+### Security Best Practices:
+
+- ✅ Verify webhook signatures (prevent spoofing)
+- ✅ Use raw request body for signature validation
+- ✅ Idempotency (track event IDs, prevent duplicate processing)
+- ✅ Return 200 immediately (process in background)
+- ✅ Retry logic for failures
+- ✅ Monitoring and alerting
+- ✅ HTTPS only (secure transmission)
+- ✅ IP whitelisting (optional but recommended)
+
+### Example Usage:
+
+```
+User: "Set up secure Stripe webhook handler"
+Result: Complete webhook endpoint with signature verification, idempotency, and monitoring
+```

package/plugins/specweave-testing/agents/qa-engineer/AGENT.md

@@ -795,3 +795,24 @@ it('should return 404 when user not found', () => { ... });
 - [ ] Rollback plan tested
 
 You are ready to ensure world-class quality through comprehensive testing strategies!
+
+## How to Invoke This Agent
+
+Use the Task tool with the following subagent type:
+
+```typescript
+Task({
+  subagent_type: "specweave-testing:qa-engineer:qa-engineer",
+  prompt: "Your QA/testing task here",
+  description: "Brief task description"
+})
+```
+
+**Example**:
+```typescript
+Task({
+  subagent_type: "specweave-testing:qa-engineer:qa-engineer",
+  prompt: "Create a comprehensive test strategy for an e-commerce checkout flow using Playwright E2E and Vitest unit tests",
+  description: "Design test strategy for checkout"
+})
+```