@primstack/cli 0.0.1

package/dist/integrations/stripe/templates/api/src/routes/stripe-webhooks.ts.template

@@ -0,0 +1,284 @@
+/**
+ * Stripe Webhook Handler
+ *
+ * This route handles incoming Stripe webhooks for subscription events.
+ *
+ * Setup:
+ * 1. Register this route in your Fastify app
+ * 2. Configure webhook endpoint in Stripe Dashboard: /webhooks/stripe
+ * 3. For local development: stripe listen --forward-to localhost:3001/webhooks/stripe
+ */
+
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { constructWebhookEvent } from '../lib/stripe.js';
+import type Stripe from 'stripe';
+
+// Import your database client
+// import { db } from '../db/index.js';
+// import { subscriptions, organizations } from '../db/schema/index.js';
+
+/**
+ * Custom error class for permanent webhook failures
+ * (should not be retried by Stripe)
+ */
+class PermanentWebhookError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PermanentWebhookError';
+  }
+}
+
+/**
+ * Register Stripe webhook routes
+ */
+export async function stripeWebhookRoutes(fastify: FastifyInstance): Promise<void> {
+  // Register a raw body parser ONLY for this route
+  // This doesn't affect other routes since we're using a route-specific hook
+  fastify.post('/webhooks/stripe', {
+    config: {
+      // Skip auth for webhooks - we verify via Stripe signature
+      skipAuth: true,
+      rawBody: true, // Request raw body for signature verification
+    },
+    // Use preValidation to get raw body before parsing
+    preValidation: async (request) => {
+      // Store raw body for webhook verification
+      // @ts-ignore - Adding custom property
+      request.rawBody = request.body;
+    },
+    handler: async (request: FastifyRequest, reply: FastifyReply) => {
+      // Handle stripe-signature header (could be string or array)
+      const signatureHeader = request.headers['stripe-signature'];
+      const signature = Array.isArray(signatureHeader) ? signatureHeader[0] : signatureHeader;
+
+      if (!signature) {
+        return reply.status(400).send({ error: 'Missing stripe-signature header' });
+      }
+
+      let event: Stripe.Event;
+
+      try {
+        // @ts-ignore - Using rawBody property
+        const body = request.rawBody || request.body;
+        event = constructWebhookEvent(body as Buffer, signature);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        fastify.log.error(`Webhook signature verification failed: ${message}`);
+        return reply.status(400).send({ error: `Webhook Error: ${message}` });
+      }
+
+      // Handle the event
+      try {
+        await handleStripeEvent(event, fastify);
+        return reply.status(200).send({ received: true });
+      } catch (err) {
+        fastify.log.error(`Error handling webhook ${event.type}: ${err}`);
+
+        // Permanent errors should return 200 to prevent retries
+        // Transient errors (DB down, network issues) should return 500 for retry
+        if (err instanceof PermanentWebhookError) {
+          fastify.log.warn(`Permanent webhook error (no retry): ${err.message}`);
+          return reply.status(200).send({ received: true, error: err.message });
+        }
+
+        // Return 500 for transient errors so Stripe retries
+        return reply.status(500).send({ error: 'Webhook handler failed, will retry' });
+      }
+    },
+  });
+}
+
+/**
+ * Handle Stripe webhook events
+ */
+async function handleStripeEvent(
+  event: Stripe.Event,
+  fastify: FastifyInstance
+): Promise<void> {
+  fastify.log.info(`Processing Stripe event: ${event.type}`);
+
+  switch (event.type) {
+    case 'checkout.session.completed':
+      await handleCheckoutCompleted(event.data.object as Stripe.Checkout.Session, fastify);
+      break;
+
+    case 'customer.subscription.created':
+      await handleSubscriptionCreated(event.data.object as Stripe.Subscription, fastify);
+      break;
+
+    case 'customer.subscription.updated':
+      await handleSubscriptionUpdated(event.data.object as Stripe.Subscription, fastify);
+      break;
+
+    case 'customer.subscription.deleted':
+      await handleSubscriptionDeleted(event.data.object as Stripe.Subscription, fastify);
+      break;
+
+    case 'invoice.payment_succeeded':
+      await handleInvoicePaymentSucceeded(event.data.object as Stripe.Invoice, fastify);
+      break;
+
+    case 'invoice.payment_failed':
+      await handleInvoicePaymentFailed(event.data.object as Stripe.Invoice, fastify);
+      break;
+
+    default:
+      fastify.log.info(`Unhandled event type: ${event.type}`);
+  }
+}
+
+/**
+ * Handle checkout.session.completed
+ * Called when a customer completes checkout
+ */
+async function handleCheckoutCompleted(
+  session: Stripe.Checkout.Session,
+  fastify: FastifyInstance
+): Promise<void> {
+  fastify.log.info(`Checkout completed: ${session.id}`);
+
+  // Get metadata from the session
+  const organizationId = session.metadata?.organizationId;
+  const userId = session.metadata?.userId;
+
+  if (!organizationId) {
+    fastify.log.warn('Checkout session missing organizationId in metadata');
+    return;
+  }
+
+  // TODO: Update your database
+  // Example:
+  // await db.update(organizations)
+  //   .set({
+  //     stripeCustomerId: session.customer as string,
+  //     stripeSubscriptionId: session.subscription as string,
+  //   })
+  //   .where(eq(organizations.id, organizationId));
+}
+
+/**
+ * Handle customer.subscription.created
+ */
+async function handleSubscriptionCreated(
+  subscription: Stripe.Subscription,
+  fastify: FastifyInstance
+): Promise<void> {
+  fastify.log.info(`Subscription created: ${subscription.id}`);
+
+  const customerId = subscription.customer as string;
+  const priceId = subscription.items.data[0]?.price.id;
+  const lookupKey = subscription.items.data[0]?.price.lookup_key;
+
+  // TODO: Create subscription record in your database
+  // Example:
+  // await db.insert(subscriptions).values({
+  //   stripeSubscriptionId: subscription.id,
+  //   stripeCustomerId: customerId,
+  //   status: subscription.status,
+  //   priceLookupKey: lookupKey,
+  //   currentPeriodStart: new Date(subscription.current_period_start * 1000),
+  //   currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+  // });
+}
+
+/**
+ * Handle customer.subscription.updated
+ */
+async function handleSubscriptionUpdated(
+  subscription: Stripe.Subscription,
+  fastify: FastifyInstance
+): Promise<void> {
+  fastify.log.info(`Subscription updated: ${subscription.id}`);
+
+  // Common updates:
+  // - Status change (active, past_due, canceled, etc.)
+  // - Plan change (different price)
+  // - Cancel at period end
+
+  // TODO: Update subscription in your database
+  // Example:
+  // await db.update(subscriptions)
+  //   .set({
+  //     status: subscription.status,
+  //     priceLookupKey: subscription.items.data[0]?.price.lookup_key,
+  //     cancelAtPeriodEnd: subscription.cancel_at_period_end,
+  //     currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+  //   })
+  //   .where(eq(subscriptions.stripeSubscriptionId, subscription.id));
+}
+
+/**
+ * Handle customer.subscription.deleted
+ */
+async function handleSubscriptionDeleted(
+  subscription: Stripe.Subscription,
+  fastify: FastifyInstance
+): Promise<void> {
+  fastify.log.info(`Subscription deleted: ${subscription.id}`);
+
+  // TODO: Update subscription status in your database
+  // Example:
+  // await db.update(subscriptions)
+  //   .set({
+  //     status: 'canceled',
+  //     canceledAt: new Date(),
+  //   })
+  //   .where(eq(subscriptions.stripeSubscriptionId, subscription.id));
+
+  // You might want to:
+  // - Downgrade the organization to free plan
+  // - Send a cancellation email
+  // - Revoke premium features
+}
+
+/**
+ * Handle invoice.payment_succeeded
+ */
+async function handleInvoicePaymentSucceeded(
+  invoice: Stripe.Invoice,
+  fastify: FastifyInstance
+): Promise<void> {
+  fastify.log.info(`Invoice payment succeeded: ${invoice.id}`);
+
+  // This is called for:
+  // - Successful subscription renewals
+  // - Successful payment after failed payment
+
+  // TODO: You might want to:
+  // - Update subscription status if it was past_due
+  // - Send a receipt email
+  // - Log the payment for accounting
+}
+
+/**
+ * Handle invoice.payment_failed
+ */
+async function handleInvoicePaymentFailed(
+  invoice: Stripe.Invoice,
+  fastify: FastifyInstance
+): Promise<void> {
+  fastify.log.info(`Invoice payment failed: ${invoice.id}`);
+
+  const customerId = invoice.customer as string;
+  const subscriptionId = invoice.subscription as string;
+
+  // TODO: Handle failed payment
+  // - Update subscription status to past_due
+  // - Send a failed payment email
+  // - Notify admin
+
+  // Example:
+  // if (subscriptionId) {
+  //   await db.update(subscriptions)
+  //     .set({ status: 'past_due' })
+  //     .where(eq(subscriptions.stripeSubscriptionId, subscriptionId));
+  // }
+
+  // Get customer email for notification
+  // const customer = await stripe.customers.retrieve(customerId);
+  // if (customer && !customer.deleted) {
+  //   await sendPaymentFailedEmail(customer.email);
+  // }
+}
+
+export default stripeWebhookRoutes;

package/dist/integrations/stripe/templates/api/stripe.config.ts.template

@@ -0,0 +1,178 @@
+/**
+ * Stripe Configuration
+ *
+ * This file contains all Stripe-related configuration including:
+ * - API credentials (per environment)
+ * - Product definitions with versioned pricing
+ * - Usage meters for metered billing
+ *
+ * IMPORTANT: This file contains sensitive information.
+ * Never commit API keys - use environment variables instead.
+ */
+
+import type { StripeConfig } from '@{{PROJECT_NAME}}/shared/stripe-types';
+
+export const stripeConfig: StripeConfig = {
+  /**
+   * Environment credentials
+   * Keys are loaded from environment variables
+   */
+  environments: {
+    test: {
+      secretKey: process.env.STRIPE_TEST_SECRET_KEY || '',
+      publishableKey: process.env.STRIPE_TEST_PUBLISHABLE_KEY || '',
+      webhookSecret: process.env.STRIPE_TEST_WEBHOOK_SECRET || '',
+    },
+    live: {
+      secretKey: process.env.STRIPE_LIVE_SECRET_KEY || '',
+      publishableKey: process.env.STRIPE_LIVE_PUBLISHABLE_KEY || '',
+      webhookSecret: process.env.STRIPE_LIVE_WEBHOOK_SECRET || '',
+    },
+  },
+
+  /**
+   * Product definitions
+   *
+   * Each product has:
+   * - Versioned pricing (for grandfathering existing customers)
+   * - Feature flags and limits
+   * - Stripe product IDs (populated by `prim stripe sync`)
+   *
+   * Price lookup keys follow the format: {slug}_{interval}_v{version}
+   * Example: pro_monthly_v1, pro_yearly_v2
+   */
+  products: {
+    free: {
+      name: 'Free',
+      slug: 'free',
+      description: 'Perfect for getting started',
+      features: [
+        '1 project',
+        '100 API calls/month',
+        'Community support',
+      ],
+      limits: {
+        projects: 1,
+        apiCalls: 100,
+        storage: 100_000_000, // 100 MB
+        seats: 1,
+      },
+      prices: {
+        monthly: [
+          {
+            version: 1,
+            lookupKey: 'free_monthly_v1',
+            amountCents: 0,
+            isDefault: true,
+          },
+        ],
+        yearly: [
+          {
+            version: 1,
+            lookupKey: 'free_yearly_v1',
+            amountCents: 0,
+            isDefault: true,
+          },
+        ],
+      },
+    },
+
+    pro: {
+      name: 'Pro',
+      slug: 'pro',
+      description: 'For professionals and small teams',
+      features: [
+        'Unlimited projects',
+        '10,000 API calls/month',
+        'Priority support',
+        '10 team members',
+      ],
+      limits: {
+        projects: -1, // unlimited
+        apiCalls: 10_000,
+        storage: 10_000_000_000, // 10 GB
+        seats: 10,
+      },
+      highlighted: true,
+      prices: {
+        monthly: [
+          {
+            version: 1,
+            lookupKey: 'pro_monthly_v1',
+            amountCents: 2900, // $29/mo
+            isDefault: true,
+          },
+        ],
+        yearly: [
+          {
+            version: 1,
+            lookupKey: 'pro_yearly_v1',
+            amountCents: 29000, // $290/yr (2 months free)
+            isDefault: true,
+          },
+        ],
+      },
+    },
+
+    enterprise: {
+      name: 'Enterprise',
+      slug: 'enterprise',
+      description: 'For large organizations',
+      features: [
+        'Everything in Pro',
+        'Unlimited API calls',
+        'Dedicated support',
+        'Unlimited team members',
+        'Custom integrations',
+        'SLA guarantee',
+      ],
+      limits: {
+        projects: -1,
+        apiCalls: -1,
+        storage: -1,
+        seats: -1,
+      },
+      prices: {
+        monthly: [
+          {
+            version: 1,
+            lookupKey: 'enterprise_monthly_v1',
+            amountCents: 9900, // $99/mo
+            isDefault: true,
+          },
+        ],
+        yearly: [
+          {
+            version: 1,
+            lookupKey: 'enterprise_yearly_v1',
+            amountCents: 99000, // $990/yr
+            isDefault: true,
+          },
+        ],
+      },
+    },
+  },
+
+  /**
+   * Usage meters (for usage-based billing)
+   * These are optional and require Stripe Billing Meters
+   */
+  meters: {
+    // apiCalls: {
+    //   displayName: 'API Calls',
+    //   stripeMeterEventName: 'api_call',
+    //   aggregation: 'sum',
+    // },
+  },
+
+  /**
+   * Customer portal configuration
+   */
+  customerPortal: {
+    allowCancellations: true,
+    allowPlanChanges: true,
+    allowPaymentMethodUpdates: true,
+  },
+};
+
+export default stripeConfig;

package/dist/integrations/stripe/templates/shared/src/pricing.ts.template

@@ -0,0 +1,117 @@
+/**
+ * Public Pricing Data
+ *
+ * This file contains ONLY public pricing information that is safe to expose
+ * to the frontend. It does NOT include:
+ * - Stripe IDs
+ * - Price versions (only current default prices)
+ * - Internal limits
+ *
+ * For the full config with Stripe IDs and versioning, see apps/api/stripe.config.ts
+ */
+
+export interface PublicPlan {
+  slug: string;
+  name: string;
+  description: string;
+  priceMonthly: number; // cents
+  priceYearly: number; // cents
+  features: string[];
+  highlighted?: boolean;
+  cta?: string;
+}
+
+/**
+ * Public pricing plans for display
+ *
+ * This is the SINGLE SOURCE OF TRUTH for pricing display.
+ * Update this when prices change.
+ */
+export const PRICING_PLANS: PublicPlan[] = [
+  {
+    slug: 'free',
+    name: 'Free',
+    description: 'Perfect for getting started',
+    priceMonthly: 0,
+    priceYearly: 0,
+    features: [
+      '1 project',
+      '100 API calls/month',
+      'Community support',
+    ],
+    cta: 'Get Started',
+  },
+  {
+    slug: 'pro',
+    name: 'Pro',
+    description: 'For professionals and small teams',
+    priceMonthly: 2900, // $29
+    priceYearly: 29000, // $290 (2 months free)
+    features: [
+      'Unlimited projects',
+      '10,000 API calls/month',
+      'Priority support',
+      '10 team members',
+    ],
+    highlighted: true,
+    cta: 'Start Free Trial',
+  },
+  {
+    slug: 'enterprise',
+    name: 'Enterprise',
+    description: 'For large organizations',
+    priceMonthly: 9900, // $99
+    priceYearly: 99000, // $990
+    features: [
+      'Everything in Pro',
+      'Unlimited API calls',
+      'Dedicated support',
+      'Unlimited team members',
+      'Custom integrations',
+      'SLA guarantee',
+    ],
+    cta: 'Contact Sales',
+  },
+];
+
+/**
+ * Format a price in cents as a currency string
+ */
+export function formatPrice(cents: number, currency = 'USD'): string {
+  if (cents === 0) return 'Free';
+
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 0,
+  }).format(cents / 100);
+}
+
+/**
+ * Get a plan by slug
+ */
+export function getPlanBySlug(slug: string): PublicPlan | undefined {
+  return PRICING_PLANS.find((plan) => plan.slug === slug);
+}
+
+/**
+ * Get the monthly/yearly savings percentage
+ */
+export function getYearlySavingsPercent(plan: PublicPlan): number {
+  if (plan.priceMonthly === 0) return 0;
+  const yearlyFromMonthly = plan.priceMonthly * 12;
+  const savings = yearlyFromMonthly - plan.priceYearly;
+  return Math.round((savings / yearlyFromMonthly) * 100);
+}
+
+/**
+ * Generate lookup key for checkout
+ */
+export function getPriceLookupKey(
+  slug: string,
+  interval: 'monthly' | 'yearly',
+  version = 1
+): string {
+  return `${slug}_${interval}_v${version}`;
+}

package/dist/integrations/stripe/templates/shared/src/stripe-types.ts.template

@@ -0,0 +1,133 @@
+/**
+ * Stripe Types
+ *
+ * Shared type definitions for Stripe configuration and billing.
+ */
+
+export type StripeEnvironment = 'test' | 'live';
+export type BillingInterval = 'monthly' | 'yearly';
+
+/**
+ * Stripe credentials for an environment
+ */
+export interface StripeCredentials {
+  secretKey: string;
+  publishableKey: string;
+  webhookSecret: string;
+}
+
+/**
+ * Price version for versioned pricing
+ *
+ * When you change prices, existing customers keep their old prices.
+ * New customers get the latest (isDefault: true) price.
+ */
+export interface PriceVersion {
+  /** Version number (increment for each price change) */
+  version: number;
+
+  /** Lookup key for Stripe (format: {slug}_{interval}_v{version}) */
+  lookupKey: string;
+
+  /** Price in cents */
+  amountCents: number;
+
+  /** Whether this is the current default price for new customers */
+  isDefault?: boolean;
+
+  /** Date when this price was deprecated */
+  deprecatedAt?: string;
+
+  /** Stripe price ID (populated by `prim stripe sync`) */
+  stripePriceId?: Record<StripeEnvironment, string>;
+}
+
+/**
+ * Plan/feature limits
+ * Use -1 for unlimited
+ */
+export interface PlanLimits {
+  projects: number;
+  apiCalls: number;
+  storage: number;
+  seats: number;
+  [key: string]: number;
+}
+
+/**
+ * Product configuration
+ */
+export interface ProductConfig {
+  name: string;
+  slug: string;
+  description: string;
+  features: string[];
+  limits: PlanLimits;
+  highlighted?: boolean;
+
+  /** Stripe product ID (populated by `prim stripe sync`) */
+  stripeProductId?: Record<StripeEnvironment, string>;
+
+  /** Versioned prices per billing interval */
+  prices: {
+    monthly: PriceVersion[];
+    yearly: PriceVersion[];
+  };
+}
+
+/**
+ * Usage meter configuration
+ */
+export interface MeterConfig {
+  displayName: string;
+  stripeMeterEventName: string;
+  aggregation: 'sum' | 'max' | 'last';
+}
+
+/**
+ * Customer portal configuration
+ */
+export interface CustomerPortalConfig {
+  allowCancellations: boolean;
+  allowPlanChanges: boolean;
+  allowPaymentMethodUpdates: boolean;
+}
+
+/**
+ * Full Stripe configuration
+ */
+export interface StripeConfig {
+  environments: Record<StripeEnvironment, StripeCredentials>;
+  products: Record<string, ProductConfig>;
+  meters?: Record<string, MeterConfig>;
+  customerPortal?: CustomerPortalConfig;
+}
+
+/**
+ * Get the default price for a product and interval
+ */
+export function getDefaultPrice(
+  product: ProductConfig,
+  interval: BillingInterval
+): PriceVersion | undefined {
+  const prices = product.prices[interval];
+  return prices.find((p) => p.isDefault) || prices[prices.length - 1];
+}
+
+/**
+ * Get price by lookup key from all products
+ */
+export function findPriceByLookupKey(
+  config: StripeConfig,
+  lookupKey: string
+): { product: ProductConfig; price: PriceVersion; interval: BillingInterval } | undefined {
+  for (const product of Object.values(config.products)) {
+    for (const interval of ['monthly', 'yearly'] as const) {
+      const price = product.prices[interval].find((p) => p.lookupKey === lookupKey);
+      if (price) {
+        return { product, price, interval };
+      }
+    }
+  }
+  return undefined;
+}