@aethex.os/stripe

Stripe subscription helpers for SaaS apps — checkout sessions, billing portal, and webhook event handling in a few lines of code.

Install

npm install @aethex.os/stripe stripe

Checkout

import { createStripeClient, createCheckoutSession } from "@aethex.os/stripe";

const stripe = createStripeClient({ stripeSecretKey: process.env.STRIPE_SECRET_KEY! });

const { url } = await createCheckoutSession(stripe, {
  customerEmail: user.email,
  plan: { name: "Pro", priceMonthly: 900 }, // $9/mo in cents
  successUrl: "https://myapp.com/dashboard?success=1",
  cancelUrl: "https://myapp.com/pricing",
  metadata: { userId: user.id, plan: "pro" },
});

res.redirect(url);

Use an existing Stripe Price ID instead of inline pricing:

const { url } = await createCheckoutSession(stripe, {
  customerId: user.stripeCustomerId,
  plan: { name: "Pro", priceMonthly: 900, priceId: process.env.STRIPE_PRO_PRICE_ID },
  successUrl: "https://myapp.com/dashboard",
  cancelUrl: "https://myapp.com/pricing",
  metadata: { userId: user.id, plan: "pro" },
  trialDays: 14,
});

Billing Portal

import { createBillingPortalSession } from "@aethex.os/stripe";

const url = await createBillingPortalSession(stripe, user.stripeCustomerId, "https://myapp.com/settings");
res.redirect(url);

Webhooks

import { parseRawBody, constructWebhookEvent, handleSubscriptionEvent } from "@aethex.os/stripe";

app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
  const rawBody = await parseRawBody(req);
  const event = constructWebhookEvent(stripe, rawBody, req.headers["stripe-signature"]!, process.env.STRIPE_WEBHOOK_SECRET!);

  await handleSubscriptionEvent(stripe, event, {
    onCheckoutComplete: async ({ userId, plan, subscriptionId }) => {
      await db.users.update(userId, { plan, stripeSubscriptionId: subscriptionId });
    },
    onSubscriptionUpdated: async ({ userId, plan, status }) => {
      if (status === "canceled") await db.users.update(userId, { plan: "free" });
    },
    onSubscriptionDeleted: async ({ userId }) => {
      await db.users.update(userId, { plan: "free", stripeSubscriptionId: null });
    },
  });

  res.json({ received: true });
});

API

createStripeClient(config)

Returns a configured Stripe instance.

createOrRetrieveCustomer(stripe, opts)

Returns an existing Stripe customer ID or creates a new one.

createCheckoutSession(stripe, opts)

Creates a Stripe Checkout session. Returns { sessionId, url }.

createBillingPortalSession(stripe, customerId, returnUrl)

Returns the billing portal URL for a customer.

parseRawBody(req)

Reads the raw request body as a string (needed for webhook signature verification).

constructWebhookEvent(stripe, rawBody, signature, secret)

Verifies and constructs a Stripe.Event.

handleSubscriptionEvent(stripe, event, handlers, getUserId?)

Routes a Stripe event to the appropriate handler. Supports onCheckoutComplete, onSubscriptionUpdated, onSubscriptionDeleted, onPaymentSucceeded, onPaymentFailed.

Part of the @aethex.os toolkit.