@codaijs/keel 0.1.0

package/sails/stripe/files/backend/routes/stripe.ts

@@ -0,0 +1,154 @@
+import { Router, type Request, type Response } from "express";
+import { eq } from "drizzle-orm";
+import { db } from "../db";
+import { customers, subscriptions } from "../db/schema/stripe";
+import {
+  createOrGetCustomer,
+  createCheckoutSession,
+  createPortalSession,
+  handleWebhookEvent,
+} from "../services/stripe";
+import { requireAuth } from "../middleware/auth";
+
+export const stripeRouter = Router();
+
+// ---------------------------------------------------------------------------
+// POST /create-checkout-session
+// ---------------------------------------------------------------------------
+
+stripeRouter.post(
+  "/create-checkout-session",
+  requireAuth,
+  async (req: Request, res: Response) => {
+    try {
+      const { priceId } = req.body;
+
+      if (!priceId || typeof priceId !== "string") {
+        return res.status(400).json({ error: "priceId is required" });
+      }
+
+      const user = req.user!;
+      const stripeCustomerId = await createOrGetCustomer(user.id, user.email);
+
+      const baseUrl = `${req.protocol}://${req.get("host")}`;
+      const session = await createCheckoutSession(
+        stripeCustomerId,
+        priceId,
+        `${baseUrl}/checkout/success?session_id={CHECKOUT_SESSION_ID}`,
+        `${baseUrl}/checkout/cancel`
+      );
+
+      return res.json({ url: session.url });
+    } catch (error) {
+      console.error("Error creating checkout session:", error);
+      return res.status(500).json({ error: "Failed to create checkout session" });
+    }
+  }
+);
+
+// ---------------------------------------------------------------------------
+// POST /create-portal-session
+// ---------------------------------------------------------------------------
+
+stripeRouter.post(
+  "/create-portal-session",
+  requireAuth,
+  async (req: Request, res: Response) => {
+    try {
+      const user = req.user!;
+
+      const customer = await db.query.customers.findFirst({
+        where: eq(customers.userId, user.id),
+      });
+
+      if (!customer) {
+        return res.status(404).json({ error: "No subscription found" });
+      }
+
+      const baseUrl = `${req.protocol}://${req.get("host")}`;
+      const session = await createPortalSession(
+        customer.stripeCustomerId,
+        `${baseUrl}/settings`
+      );
+
+      return res.json({ url: session.url });
+    } catch (error) {
+      console.error("Error creating portal session:", error);
+      return res.status(500).json({ error: "Failed to create portal session" });
+    }
+  }
+);
+
+// ---------------------------------------------------------------------------
+// POST /webhook
+// ---------------------------------------------------------------------------
+
+/**
+ * Stripe webhook endpoint.
+ *
+ * IMPORTANT: This route must receive the raw request body (not parsed as JSON).
+ * The Express app must be configured with:
+ *
+ *   app.use("/api/stripe/webhook", express.raw({ type: "application/json" }));
+ *
+ * This should be placed BEFORE the general express.json() middleware.
+ */
+stripeRouter.post("/webhook", async (req: Request, res: Response) => {
+  const signature = req.headers["stripe-signature"];
+
+  if (!signature || typeof signature !== "string") {
+    return res.status(400).json({ error: "Missing stripe-signature header" });
+  }
+
+  try {
+    await handleWebhookEvent(req.body, signature);
+    return res.json({ received: true });
+  } catch (error) {
+    console.error("Webhook error:", error);
+    return res
+      .status(400)
+      .json({ error: error instanceof Error ? error.message : "Webhook failed" });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// GET /subscription
+// ---------------------------------------------------------------------------
+
+stripeRouter.get(
+  "/subscription",
+  requireAuth,
+  async (req: Request, res: Response) => {
+    try {
+      const user = req.user!;
+
+      const customer = await db.query.customers.findFirst({
+        where: eq(customers.userId, user.id),
+      });
+
+      if (!customer) {
+        return res.json({ subscription: null });
+      }
+
+      const subscription = await db.query.subscriptions.findFirst({
+        where: eq(subscriptions.customerId, customer.id),
+        orderBy: (sub, { desc }) => [desc(sub.createdAt)],
+      });
+
+      return res.json({
+        subscription: subscription
+          ? {
+              id: subscription.id,
+              status: subscription.status,
+              priceId: subscription.stripePriceId,
+              currentPeriodEnd: subscription.currentPeriodEnd,
+              cancelAtPeriodEnd: subscription.cancelAtPeriodEnd,
+            }
+          : null,
+      });
+    } catch (error) {
+      console.error("Error fetching subscription:", error);
+      return res.status(500).json({ error: "Failed to fetch subscription" });
+    }
+  }
+);

package/sails/stripe/files/backend/schema/stripe.ts

@@ -0,0 +1,74 @@
+import {
+  pgTable,
+  text,
+  timestamp,
+  boolean,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { relations } from "drizzle-orm";
+import { users } from "./users";
+
+/**
+ * Stripe customers table.
+ *
+ * Maps internal user IDs to Stripe customer IDs. Each user has at most one
+ * Stripe customer record, created on their first checkout session.
+ */
+export const customers = pgTable("stripe_customers", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  userId: text("user_id")
+    .notNull()
+    .unique()
+    .references(() => users.id, { onDelete: "cascade" }),
+  stripeCustomerId: text("stripe_customer_id").notNull().unique(),
+  createdAt: timestamp("created_at", { withTimezone: true })
+    .notNull()
+    .defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true })
+    .notNull()
+    .defaultNow()
+    .$onUpdate(() => new Date()),
+});
+
+export const customersRelations = relations(customers, ({ one, many }) => ({
+  user: one(users, {
+    fields: [customers.userId],
+    references: [users.id],
+  }),
+  subscriptions: many(subscriptions),
+}));
+
+/**
+ * Stripe subscriptions table.
+ *
+ * Tracks the state of each Stripe subscription. Updated via webhooks whenever
+ * Stripe fires subscription lifecycle events.
+ */
+export const subscriptions = pgTable("stripe_subscriptions", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  customerId: uuid("customer_id")
+    .notNull()
+    .references(() => customers.id, { onDelete: "cascade" }),
+  stripeSubscriptionId: text("stripe_subscription_id").notNull().unique(),
+  status: text("status").notNull().default("incomplete"),
+  stripePriceId: text("stripe_price_id").notNull(),
+  currentPeriodStart: timestamp("current_period_start", {
+    withTimezone: true,
+  }),
+  currentPeriodEnd: timestamp("current_period_end", { withTimezone: true }),
+  cancelAtPeriodEnd: boolean("cancel_at_period_end").notNull().default(false),
+  createdAt: timestamp("created_at", { withTimezone: true })
+    .notNull()
+    .defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true })
+    .notNull()
+    .defaultNow()
+    .$onUpdate(() => new Date()),
+});
+
+export const subscriptionsRelations = relations(subscriptions, ({ one }) => ({
+  customer: one(customers, {
+    fields: [subscriptions.customerId],
+    references: [customers.id],
+  }),
+}));

package/sails/stripe/files/backend/services/stripe.ts

@@ -0,0 +1,224 @@
+import Stripe from "stripe";
+import { eq } from "drizzle-orm";
+import { db } from "../db";
+import { customers, subscriptions } from "../db/schema/stripe";
+import { env } from "../env";
+
+// ---------------------------------------------------------------------------
+// Stripe SDK instance
+// ---------------------------------------------------------------------------
+
+export const stripe = new Stripe(env.STRIPE_SECRET_KEY, {
+  apiVersion: "2024-12-18.acacia",
+  typescript: true,
+});
+
+// ---------------------------------------------------------------------------
+// Customer management
+// ---------------------------------------------------------------------------
+
+/**
+ * Retrieve the existing Stripe customer for a user, or create one.
+ */
+export async function createOrGetCustomer(
+  userId: string,
+  email: string
+): Promise<string> {
+  // Check for existing customer record
+  const existing = await db.query.customers.findFirst({
+    where: eq(customers.userId, userId),
+  });
+
+  if (existing) {
+    return existing.stripeCustomerId;
+  }
+
+  // Create a new Stripe customer
+  const stripeCustomer = await stripe.customers.create({
+    email,
+    metadata: { userId },
+  });
+
+  // Persist the mapping
+  await db.insert(customers).values({
+    userId,
+    stripeCustomerId: stripeCustomer.id,
+  });
+
+  return stripeCustomer.id;
+}
+
+// ---------------------------------------------------------------------------
+// Checkout session
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Stripe Checkout session for a subscription.
+ */
+export async function createCheckoutSession(
+  customerId: string,
+  priceId: string,
+  successUrl: string,
+  cancelUrl: string
+): Promise<Stripe.Checkout.Session> {
+  return stripe.checkout.sessions.create({
+    customer: customerId,
+    mode: "subscription",
+    payment_method_types: ["card"],
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: successUrl,
+    cancel_url: cancelUrl,
+    subscription_data: {
+      metadata: { customerId },
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Customer portal session
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Stripe Customer Portal session so the user can manage their
+ * subscription, update payment methods, or cancel.
+ */
+export async function createPortalSession(
+  customerId: string,
+  returnUrl: string
+): Promise<Stripe.BillingPortal.Session> {
+  return stripe.billingPortal.sessions.create({
+    customer: customerId,
+    return_url: returnUrl,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Webhook event handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify and process an incoming Stripe webhook event.
+ */
+export async function handleWebhookEvent(
+  payload: string | Buffer,
+  signature: string
+): Promise<void> {
+  const event = stripe.webhooks.constructEvent(
+    payload,
+    signature,
+    env.STRIPE_WEBHOOK_SECRET
+  );
+
+  switch (event.type) {
+    case "checkout.session.completed": {
+      const session = event.data.object as Stripe.Checkout.Session;
+      await handleCheckoutCompleted(session);
+      break;
+    }
+
+    case "customer.subscription.updated": {
+      const subscription = event.data.object as Stripe.Subscription;
+      await handleSubscriptionUpdated(subscription);
+      break;
+    }
+
+    case "customer.subscription.deleted": {
+      const subscription = event.data.object as Stripe.Subscription;
+      await handleSubscriptionDeleted(subscription);
+      break;
+    }
+
+    default:
+      console.log(`Unhandled Stripe event type: ${event.type}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal event handlers
+// ---------------------------------------------------------------------------
+
+async function handleCheckoutCompleted(
+  session: Stripe.Checkout.Session
+): Promise<void> {
+  if (session.mode !== "subscription" || !session.subscription) return;
+
+  const stripeSubscriptionId =
+    typeof session.subscription === "string"
+      ? session.subscription
+      : session.subscription.id;
+
+  const stripeCustomerId =
+    typeof session.customer === "string"
+      ? session.customer
+      : session.customer?.id;
+
+  if (!stripeCustomerId) return;
+
+  // Look up the internal customer record
+  const customer = await db.query.customers.findFirst({
+    where: eq(customers.stripeCustomerId, stripeCustomerId),
+  });
+
+  if (!customer) {
+    console.error(
+      `No customer record found for Stripe customer ${stripeCustomerId}`
+    );
+    return;
+  }
+
+  // Fetch the full subscription from Stripe to get price info
+  const stripeSub = await stripe.subscriptions.retrieve(stripeSubscriptionId);
+  const priceId = stripeSub.items.data[0]?.price.id ?? "";
+
+  // Upsert the subscription record
+  await db
+    .insert(subscriptions)
+    .values({
+      customerId: customer.id,
+      stripeSubscriptionId,
+      status: stripeSub.status,
+      stripePriceId: priceId,
+      currentPeriodStart: new Date(stripeSub.current_period_start * 1000),
+      currentPeriodEnd: new Date(stripeSub.current_period_end * 1000),
+      cancelAtPeriodEnd: stripeSub.cancel_at_period_end,
+    })
+    .onConflictDoUpdate({
+      target: subscriptions.stripeSubscriptionId,
+      set: {
+        status: stripeSub.status,
+        stripePriceId: priceId,
+        currentPeriodStart: new Date(stripeSub.current_period_start * 1000),
+        currentPeriodEnd: new Date(stripeSub.current_period_end * 1000),
+        cancelAtPeriodEnd: stripeSub.cancel_at_period_end,
+      },
+    });
+}
+
+async function handleSubscriptionUpdated(
+  subscription: Stripe.Subscription
+): Promise<void> {
+  const priceId = subscription.items.data[0]?.price.id ?? "";
+
+  await db
+    .update(subscriptions)
+    .set({
+      status: subscription.status,
+      stripePriceId: priceId,
+      currentPeriodStart: new Date(subscription.current_period_start * 1000),
+      currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+      cancelAtPeriodEnd: subscription.cancel_at_period_end,
+    })
+    .where(eq(subscriptions.stripeSubscriptionId, subscription.id));
+}
+
+async function handleSubscriptionDeleted(
+  subscription: Stripe.Subscription
+): Promise<void> {
+  await db
+    .update(subscriptions)
+    .set({
+      status: "canceled",
+      cancelAtPeriodEnd: false,
+    })
+    .where(eq(subscriptions.stripeSubscriptionId, subscription.id));
+}

package/sails/stripe/files/frontend/components/SubscriptionStatus.tsx

@@ -0,0 +1,135 @@
+import { useSubscription } from "@/hooks/useSubscription";
+
+/**
+ * Displays the current user's subscription status with options to manage,
+ * upgrade, or subscribe.
+ */
+export function SubscriptionStatus() {
+  const { subscription, isLoading, error } = useSubscription();
+
+  const handleManage = async () => {
+    try {
+      const response = await fetch("/api/stripe/create-portal-session", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        credentials: "include",
+      });
+      const data = await response.json();
+      if (data.url) {
+        window.location.href = data.url;
+      }
+    } catch (err) {
+      console.error("Failed to open customer portal:", err);
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <div className="animate-pulse rounded-lg border border-gray-200 p-6 dark:border-gray-700">
+        <div className="h-4 w-32 rounded bg-gray-200 dark:bg-gray-700" />
+        <div className="mt-3 h-3 w-48 rounded bg-gray-200 dark:bg-gray-700" />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="rounded-lg border border-red-200 bg-red-50 p-6 dark:border-red-800 dark:bg-red-900/20">
+        <p className="text-sm text-red-600 dark:text-red-400">
+          Failed to load subscription status.
+        </p>
+      </div>
+    );
+  }
+
+  // No subscription — show upgrade prompt
+  if (!subscription) {
+    return (
+      <div className="rounded-lg border border-gray-200 p-6 dark:border-gray-700">
+        <div className="flex items-center justify-between">
+          <div>
+            <h3 className="text-sm font-semibold text-gray-900 dark:text-white">
+              Free Plan
+            </h3>
+            <p className="mt-1 text-sm text-gray-500 dark:text-gray-400">
+              Upgrade to unlock premium features.
+            </p>
+          </div>
+          <a
+            href="/pricing"
+            className="rounded-lg bg-blue-600 px-4 py-2 text-sm font-semibold text-white hover:bg-blue-700"
+          >
+            Upgrade
+          </a>
+        </div>
+      </div>
+    );
+  }
+
+  // Status badge colors
+  const statusColors: Record<string, string> = {
+    active: "bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400",
+    trialing: "bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400",
+    past_due: "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400",
+    canceled: "bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400",
+    incomplete: "bg-gray-100 text-gray-800 dark:bg-gray-900/30 dark:text-gray-400",
+  };
+
+  const statusLabel: Record<string, string> = {
+    active: "Active",
+    trialing: "Trial",
+    past_due: "Past Due",
+    canceled: "Canceled",
+    incomplete: "Incomplete",
+  };
+
+  const periodEnd = subscription.currentPeriodEnd
+    ? new Date(subscription.currentPeriodEnd).toLocaleDateString(undefined, {
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+      })
+    : null;
+
+  return (
+    <div className="rounded-lg border border-gray-200 p-6 dark:border-gray-700">
+      <div className="flex items-start justify-between">
+        <div>
+          <div className="flex items-center gap-2">
+            <h3 className="text-sm font-semibold text-gray-900 dark:text-white">
+              Subscription
+            </h3>
+            <span
+              className={`inline-flex rounded-full px-2 py-0.5 text-xs font-medium ${
+                statusColors[subscription.status] ?? statusColors.incomplete
+              }`}
+            >
+              {statusLabel[subscription.status] ?? subscription.status}
+            </span>
+          </div>
+
+          {subscription.cancelAtPeriodEnd && (
+            <p className="mt-1 text-sm text-yellow-600 dark:text-yellow-400">
+              Cancels at end of billing period
+            </p>
+          )}
+
+          {periodEnd && (
+            <p className="mt-1 text-sm text-gray-500 dark:text-gray-400">
+              {subscription.cancelAtPeriodEnd
+                ? `Access until ${periodEnd}`
+                : `Renews on ${periodEnd}`}
+            </p>
+          )}
+        </div>
+
+        <button
+          onClick={handleManage}
+          className="rounded-lg border border-gray-300 px-4 py-2 text-sm font-semibold text-gray-700 hover:bg-gray-50 dark:border-gray-600 dark:text-gray-300 dark:hover:bg-gray-800"
+        >
+          Manage
+        </button>
+      </div>
+    </div>
+  );
+}

package/sails/stripe/files/frontend/hooks/useSubscription.ts

@@ -0,0 +1,86 @@
+import { useState, useEffect, useCallback } from "react";
+
+interface Subscription {
+  id: string;
+  status: string;
+  priceId: string;
+  currentPeriodEnd: string | null;
+  cancelAtPeriodEnd: boolean;
+}
+
+interface UseSubscriptionResult {
+  subscription: Subscription | null;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+/**
+ * Hook to fetch and manage the current user's subscription state.
+ *
+ * Automatically fetches on mount. Call `refetch()` to manually refresh
+ * (e.g., after returning from Stripe Checkout or the customer portal).
+ */
+export function useSubscription(): UseSubscriptionResult {
+  const [subscription, setSubscription] = useState<Subscription | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchSubscription = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const response = await fetch("/api/stripe/subscription", {
+        credentials: "include",
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch subscription: ${response.statusText}`);
+      }
+
+      const data = await response.json();
+      setSubscription(data.subscription ?? null);
+    } catch (err) {
+      setError(
+        err instanceof Error ? err : new Error("Unknown error fetching subscription")
+      );
+      setSubscription(null);
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    fetchSubscription();
+  }, [fetchSubscription]);
+
+  return {
+    subscription,
+    isLoading,
+    error,
+    refetch: fetchSubscription,
+  };
+}
+
+/**
+ * Helper to check if a subscription is in an active/usable state.
+ */
+export function isSubscriptionActive(
+  subscription: Subscription | null
+): boolean {
+  if (!subscription) return false;
+  return ["active", "trialing"].includes(subscription.status);
+}
+
+/**
+ * Helper to check if the user has a specific plan by price ID.
+ */
+export function hasPlans(
+  subscription: Subscription | null,
+  priceIds: string[]
+): boolean {
+  if (!subscription) return false;
+  if (!isSubscriptionActive(subscription)) return false;
+  return priceIds.includes(subscription.priceId);
+}