@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/payment-integration.md

@@ -0,0 +1,222 @@
+---
+name: payment-integration
+description: Payment integration patterns with Stripe, webhooks, idempotency, subscription billing, and PCI compliance.
+---
+
+# Payment Integration
+
+## When to Use
+Apply when your application needs to accept payments -- one-time purchases, subscriptions, usage-based billing, or marketplace payouts. Stripe is the default choice for most SaaS and e-commerce applications. These patterns apply broadly to any payment provider. Never store card numbers or build custom card forms unless PCI DSS compliance is already in place.
+
+## How It Works
+
+### Stripe Checkout -- One-Time Payments
+
+```typescript
+import Stripe from "stripe";
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+app.post("/api/checkout", async (req, res) => {
+  const session = await stripe.checkout.sessions.create({
+    mode: "payment",
+    customer_email: req.user.email,
+    line_items: [{
+      price_data: {
+        currency: "usd",
+        product_data: { name: req.body.productName },
+        unit_amount: req.body.priceInCents, // always cents, never dollars
+      },
+      quantity: req.body.quantity,
+    }],
+    metadata: { userId: req.user.id, orderId: req.body.orderId },
+    success_url: `${process.env.APP_URL}/checkout/success?session_id={CHECKOUT_SESSION_ID}`,
+    cancel_url: `${process.env.APP_URL}/checkout/cancel`,
+    expires_at: Math.floor(Date.now() / 1000) + 1800,
+  });
+
+  res.json({ url: session.url });
+});
+```
+
+### Subscriptions with Stripe Billing
+
+```typescript
+app.post("/api/subscribe", async (req, res) => {
+  let customerId = req.user.stripeCustomerId;
+  if (!customerId) {
+    const customer = await stripe.customers.create({
+      email: req.user.email,
+      metadata: { userId: req.user.id },
+    });
+    customerId = customer.id;
+    await db.users.update(req.user.id, { stripeCustomerId: customerId });
+  }
+
+  const session = await stripe.checkout.sessions.create({
+    mode: "subscription",
+    customer: customerId,
+    line_items: [{ price: req.body.stripePriceId, quantity: 1 }],
+    subscription_data: {
+      trial_period_days: 14,
+      metadata: { userId: req.user.id, plan: req.body.plan },
+    },
+    success_url: `${process.env.APP_URL}/dashboard?upgraded=true`,
+    cancel_url: `${process.env.APP_URL}/pricing`,
+  });
+
+  res.json({ url: session.url });
+});
+
+// Customer portal for self-service billing management
+app.post("/api/billing/portal", async (req, res) => {
+  const session = await stripe.billingPortal.sessions.create({
+    customer: req.user.stripeCustomerId,
+    return_url: `${process.env.APP_URL}/settings/billing`,
+  });
+  res.json({ url: session.url });
+});
+```
+
+### Webhook Handling -- Source of Truth
+
+Webhooks are the source of truth for payment state. The success_url page is just UI:
+
+```typescript
+app.post(
+  "/api/webhooks/stripe",
+  express.raw({ type: "application/json" }),
+  async (req, res) => {
+    const sig = req.headers["stripe-signature"] as string;
+    let event: Stripe.Event;
+
+    try {
+      event = stripe.webhooks.constructEvent(
+        req.body, sig, process.env.STRIPE_WEBHOOK_SECRET!
+      );
+    } catch {
+      return res.status(400).send("Invalid signature");
+    }
+
+    switch (event.type) {
+      case "checkout.session.completed": {
+        const session = event.data.object as Stripe.Checkout.Session;
+        await fulfillOrder(session);
+        break;
+      }
+      case "invoice.paid": {
+        const invoice = event.data.object as Stripe.Invoice;
+        await extendSubscription(invoice);
+        break;
+      }
+      case "invoice.payment_failed": {
+        const invoice = event.data.object as Stripe.Invoice;
+        await handlePaymentFailure(invoice);
+        break;
+      }
+      case "customer.subscription.deleted": {
+        const sub = event.data.object as Stripe.Subscription;
+        await revokeAccess(sub);
+        break;
+      }
+    }
+    res.json({ received: true });
+  }
+);
+```
+
+### Idempotency
+
+Payment operations must be safe to retry:
+
+```typescript
+// Stripe idempotency key tied to business entity
+const charge = await stripe.charges.create(
+  { amount: 2000, currency: "usd", customer: customerId, metadata: { orderId } },
+  { idempotencyKey: `charge-${orderId}` }
+);
+
+// Webhook deduplication
+async function processWebhook(event: Stripe.Event): Promise<void> {
+  const acquired = await redis.set(`stripe:event:${event.id}`, "1", "NX", "EX", 86400);
+  if (!acquired) return; // duplicate
+  // Process event...
+}
+
+// Database-level idempotency for fulfillment
+async function fulfillOrder(session: Stripe.Checkout.Session): Promise<void> {
+  const orderId = session.metadata!.orderId;
+  const result = await db.query(
+    `UPDATE orders SET status = 'fulfilled', stripe_session_id = $1
+     WHERE id = $2 AND status = 'pending'`,
+    [session.id, orderId]
+  );
+  if (result.rowCount === 0) return; // already fulfilled
+  await provisionAccess(orderId);
+}
+```
+
+### Refunds
+
+```typescript
+app.post("/api/orders/:id/refund", async (req, res) => {
+  const order = await db.orders.findById(req.params.id);
+  if (!order) return res.status(404).json({ error: "Order not found" });
+  if (order.userId !== req.user.id) return res.status(403).json({ error: "Forbidden" });
+
+  const daysSincePurchase = (Date.now() - order.createdAt.getTime()) / 86400000;
+  if (daysSincePurchase > 30) {
+    return res.status(400).json({ error: "Refund window closed (30 days)" });
+  }
+
+  const refund = await stripe.refunds.create(
+    {
+      payment_intent: order.stripePaymentIntentId,
+      amount: req.body.partial ? req.body.amountInCents : undefined,
+      reason: "requested_by_customer",
+    },
+    { idempotencyKey: `refund-${order.id}` }
+  );
+
+  await db.orders.update(order.id, {
+    status: refund.amount === order.totalCents ? "refunded" : "partially_refunded",
+  });
+  res.json({ refundId: refund.id, amount: refund.amount });
+});
+```
+
+### PCI Compliance Essentials
+
+```
+NEVER DO:
+- Store card numbers, CVV, or full magnetic stripe data
+- Build custom card input forms (use Stripe Elements or Checkout)
+- Log raw payment API responses containing card data
+- Send card data to your server (use client-side tokenization)
+
+ALWAYS DO:
+- Use Stripe Checkout or Elements (SAQ A compliance)
+- Verify webhook signatures on every request
+- Use HTTPS for all payment-related endpoints
+- Store only Stripe customer/subscription/payment IDs
+```
+
+## Examples
+
+| Scenario | Stripe Feature | Key Consideration |
+|----------|---------------|-------------------|
+| SaaS monthly plan | Checkout + Subscriptions | Dunning emails for failed payments |
+| One-time purchase | Checkout Session | Fulfill via webhook only |
+| Marketplace payouts | Stripe Connect | Destination charges for platform fee |
+| Usage-based billing | Metered subscriptions | Report usage via Usage Records API |
+| B2B invoicing | Invoices API | Net-30 terms, PDF generation |
+
+## Checklist
+- [ ] Payments use Stripe Checkout or Elements for PCI compliance
+- [ ] Webhook signature verified on every request
+- [ ] Webhook route uses `express.raw()`, not `express.json()`
+- [ ] All mutating Stripe calls include idempotency keys
+- [ ] Fulfillment happens in webhook handlers, not success page
+- [ ] Duplicate webhook events detected and skipped
+- [ ] Amounts always in cents (integer), never dollars (float)
+- [ ] Failed subscription payments trigger dunning sequence

package/assets/skills/pdf-generation.md

@@ -0,0 +1,307 @@
+---
+name: pdf-generation
+description: PDF generation patterns with Puppeteer, jsPDF, server-side rendering from HTML templates, streaming, and batch processing.
+---
+
+# PDF Generation Patterns
+
+## When to Use
+Generate PDFs for invoices, reports, certificates, contracts, and any document that needs consistent formatting across devices. Use Puppeteer for pixel-perfect HTML-to-PDF conversion with full CSS support. Use jsPDF for lightweight client-side generation. Choose server-side rendering when you need consistent output regardless of client, and streaming for large documents that should not be held in memory.
+
+## How It Works
+
+### Puppeteer HTML-to-PDF
+
+```typescript
+// src/pdf/puppeteer-generator.ts
+import puppeteer, { type Browser } from 'puppeteer';
+
+let browser: Browser | null = null;
+
+async function getBrowser(): Promise<Browser> {
+  if (!browser) {
+    browser = await puppeteer.launch({
+      headless: true,
+      args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-gpu'],
+    });
+  }
+  return browser;
+}
+
+export async function generatePdfFromHtml(html: string, options?: {
+  format?: 'A4' | 'Letter';
+  landscape?: boolean;
+  margin?: { top: string; right: string; bottom: string; left: string };
+  headerTemplate?: string;
+  footerTemplate?: string;
+}): Promise<Buffer> {
+  const browser = await getBrowser();
+  const page = await browser.newPage();
+
+  try {
+    await page.setContent(html, { waitUntil: 'networkidle0' });
+
+    const pdf = await page.pdf({
+      format: options?.format ?? 'A4',
+      landscape: options?.landscape ?? false,
+      printBackground: true,
+      margin: options?.margin ?? { top: '20mm', right: '15mm', bottom: '20mm', left: '15mm' },
+      displayHeaderFooter: !!(options?.headerTemplate || options?.footerTemplate),
+      headerTemplate: options?.headerTemplate ?? '',
+      footerTemplate: options?.footerTemplate ?? `
+        <div style="font-size:9px; width:100%; text-align:center; color:#666;">
+          Page <span class="pageNumber"></span> of <span class="totalPages"></span>
+        </div>
+      `,
+    });
+
+    return Buffer.from(pdf);
+  } finally {
+    await page.close();
+  }
+}
+
+// Cleanup on shutdown
+process.on('SIGTERM', async () => {
+  if (browser) await browser.close();
+});
+```
+
+### Invoice Template
+
+```typescript
+// src/pdf/templates/invoice.ts
+interface InvoiceData {
+  invoiceNumber: string;
+  date: string;
+  dueDate: string;
+  company: { name: string; address: string; email: string };
+  customer: { name: string; address: string; email: string };
+  items: Array<{ description: string; quantity: number; unitPrice: number }>;
+  taxRate: number;
+  notes?: string;
+}
+
+export function renderInvoiceHtml(data: InvoiceData): string {
+  const subtotal = data.items.reduce((sum, item) => sum + item.quantity * item.unitPrice, 0);
+  const tax = subtotal * data.taxRate;
+  const total = subtotal + tax;
+
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <style>
+    body { font-family: 'Helvetica Neue', Arial, sans-serif; color: #333; margin: 0; padding: 40px; }
+    .header { display: flex; justify-content: space-between; margin-bottom: 40px; }
+    .company-name { font-size: 24px; font-weight: 700; color: #1a1a1a; }
+    .invoice-title { font-size: 32px; font-weight: 300; color: #666; text-align: right; }
+    .meta { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin-bottom: 40px; }
+    .meta-label { font-size: 12px; text-transform: uppercase; color: #999; margin-bottom: 4px; }
+    table { width: 100%; border-collapse: collapse; margin-bottom: 30px; }
+    th { text-align: left; padding: 12px 8px; border-bottom: 2px solid #333; font-size: 12px; text-transform: uppercase; }
+    td { padding: 12px 8px; border-bottom: 1px solid #eee; }
+    .amount { text-align: right; }
+    .totals { width: 300px; margin-left: auto; }
+    .totals td { border: none; padding: 6px 8px; }
+    .totals .total { font-size: 18px; font-weight: 700; border-top: 2px solid #333; }
+    .notes { margin-top: 40px; padding: 20px; background: #f8f8f8; border-radius: 4px; font-size: 14px; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <div>
+      <div class="company-name">${data.company.name}</div>
+      <div>${data.company.address}</div>
+      <div>${data.company.email}</div>
+    </div>
+    <div class="invoice-title">INVOICE</div>
+  </div>
+
+  <div class="meta">
+    <div>
+      <div class="meta-label">Bill To</div>
+      <div><strong>${data.customer.name}</strong></div>
+      <div>${data.customer.address}</div>
+      <div>${data.customer.email}</div>
+    </div>
+    <div style="text-align: right;">
+      <div class="meta-label">Invoice #</div>
+      <div>${data.invoiceNumber}</div>
+      <div class="meta-label" style="margin-top: 8px;">Date</div>
+      <div>${data.date}</div>
+      <div class="meta-label" style="margin-top: 8px;">Due Date</div>
+      <div>${data.dueDate}</div>
+    </div>
+  </div>
+
+  <table>
+    <thead>
+      <tr><th>Description</th><th class="amount">Qty</th><th class="amount">Unit Price</th><th class="amount">Amount</th></tr>
+    </thead>
+    <tbody>
+      ${data.items.map((item) => `
+        <tr>
+          <td>${item.description}</td>
+          <td class="amount">${item.quantity}</td>
+          <td class="amount">$${item.unitPrice.toFixed(2)}</td>
+          <td class="amount">$${(item.quantity * item.unitPrice).toFixed(2)}</td>
+        </tr>
+      `).join('')}
+    </tbody>
+  </table>
+
+  <table class="totals">
+    <tr><td>Subtotal</td><td class="amount">$${subtotal.toFixed(2)}</td></tr>
+    <tr><td>Tax (${(data.taxRate * 100).toFixed(0)}%)</td><td class="amount">$${tax.toFixed(2)}</td></tr>
+    <tr class="total"><td>Total</td><td class="amount">$${total.toFixed(2)}</td></tr>
+  </table>
+
+  ${data.notes ? `<div class="notes"><strong>Notes:</strong> ${data.notes}</div>` : ''}
+</body>
+</html>`;
+}
+```
+
+### jsPDF Client-Side Generation
+
+```typescript
+// src/pdf/client-generator.ts
+import jsPDF from 'jspdf';
+import autoTable from 'jspdf-autotable';
+
+export function generateReport(data: ReportData): jsPDF {
+  const doc = new jsPDF({ orientation: 'portrait', unit: 'mm', format: 'a4' });
+
+  // Header
+  doc.setFontSize(24);
+  doc.text('Monthly Report', 20, 30);
+
+  doc.setFontSize(12);
+  doc.setTextColor(100);
+  doc.text(`Generated: ${new Date().toLocaleDateString()}`, 20, 40);
+
+  // Summary section
+  doc.setFontSize(16);
+  doc.setTextColor(0);
+  doc.text('Summary', 20, 60);
+
+  doc.setFontSize(11);
+  doc.text(`Total Revenue: $${data.revenue.toLocaleString()}`, 20, 70);
+  doc.text(`Active Users: ${data.activeUsers.toLocaleString()}`, 20, 78);
+  doc.text(`Conversion Rate: ${(data.conversionRate * 100).toFixed(1)}%`, 20, 86);
+
+  // Data table
+  autoTable(doc, {
+    startY: 100,
+    head: [['Month', 'Revenue', 'Users', 'Conversion']],
+    body: data.monthly.map((m) => [
+      m.month,
+      `$${m.revenue.toLocaleString()}`,
+      m.users.toLocaleString(),
+      `${(m.conversion * 100).toFixed(1)}%`,
+    ]),
+    styles: { fontSize: 10, cellPadding: 4 },
+    headStyles: { fillColor: [37, 99, 235], textColor: 255 },
+    alternateRowStyles: { fillColor: [245, 247, 250] },
+  });
+
+  return doc;
+}
+
+// Download in browser
+function downloadPdf(data: ReportData) {
+  const doc = generateReport(data);
+  doc.save('monthly-report.pdf');
+}
+
+// Get as blob for upload
+async function uploadPdf(data: ReportData): Promise<void> {
+  const doc = generateReport(data);
+  const blob = doc.output('blob');
+  const formData = new FormData();
+  formData.append('file', blob, 'report.pdf');
+  await fetch('/api/upload', { method: 'POST', body: formData });
+}
+```
+
+### Express PDF Endpoint with Streaming
+
+```typescript
+// src/routes/pdf.ts
+import { Router } from 'express';
+import { generatePdfFromHtml } from '../pdf/puppeteer-generator';
+import { renderInvoiceHtml } from '../pdf/templates/invoice';
+
+const router = Router();
+
+router.get('/api/invoices/:id/pdf', async (req, res) => {
+  try {
+    const invoice = await getInvoice(req.params.id);
+    if (!invoice) return res.status(404).json({ error: 'Invoice not found' });
+
+    const html = renderInvoiceHtml(invoice);
+    const pdf = await generatePdfFromHtml(html, {
+      footerTemplate: `<div style="font-size:8px;text-align:center;width:100%;color:#999;">
+        Invoice ${invoice.invoiceNumber} | Page <span class="pageNumber"></span>
+      </div>`,
+    });
+
+    res.set({
+      'Content-Type': 'application/pdf',
+      'Content-Disposition': `inline; filename="invoice-${invoice.invoiceNumber}.pdf"`,
+      'Content-Length': String(pdf.length),
+      'Cache-Control': 'private, max-age=3600',
+    });
+
+    res.send(pdf);
+  } catch (err) {
+    console.error('PDF generation failed:', err);
+    res.status(500).json({ error: 'PDF generation failed' });
+  }
+});
+
+// Batch PDF generation
+router.post('/api/invoices/batch-pdf', async (req, res) => {
+  const { invoiceIds } = req.body;
+  const archiver = require('archiver');
+  const archive = archiver('zip');
+
+  res.set({
+    'Content-Type': 'application/zip',
+    'Content-Disposition': 'attachment; filename="invoices.zip"',
+  });
+
+  archive.pipe(res);
+
+  for (const id of invoiceIds) {
+    const invoice = await getInvoice(id);
+    if (!invoice) continue;
+    const html = renderInvoiceHtml(invoice);
+    const pdf = await generatePdfFromHtml(html);
+    archive.append(pdf, { name: `invoice-${invoice.invoiceNumber}.pdf` });
+  }
+
+  await archive.finalize();
+});
+
+export default router;
+```
+
+## Examples
+
+| Method | Environment | CSS Support | Best For |
+|--------|-------------|-------------|----------|
+| Puppeteer | Server (Node.js) | Full (Chrome rendering) | Complex layouts, pixel-perfect |
+| jsPDF | Client or server | None (manual layout) | Simple reports, tables |
+| @react-pdf/renderer | Server or client | Subset (flexbox) | React-based templates |
+| wkhtmltopdf | Server (binary) | Good (WebKit) | Legacy systems |
+
+## Checklist
+- [ ] Puppeteer browser instance reused across requests (not launched per PDF)
+- [ ] Templates use print-friendly CSS (no background colors unless `printBackground: true`)
+- [ ] Page margins, headers, and footers configured with page numbers
+- [ ] PDF Content-Disposition header set correctly (inline for preview, attachment for download)
+- [ ] Large batch generations use streaming or queued processing
+- [ ] Browser instance cleaned up on server shutdown
+- [ ] Fonts embedded or using web-safe fallbacks for consistent rendering
+- [ ] PDF generation errors return proper HTTP error responses