stripe-no-webhooks 0.0.8 → 0.0.11

package/README.md

@@ -1,152 +1,166 @@
 # stripe-no-webhooks
 
-Stripe integration without dealing with webhooks. Automatically syncs Stripe data to your PostgreSQL database and provides simple callbacks for subscription events.
+Opinionated library to help you implement payments with Stripe. It syncs Stripe data to your database and gives you useful helpers to implement subscriptions and credits.
 
-## Installation
+## Why this library?
+
+This library is a wrapper on Stripe SDK (with some bells and whistles). It gives you an opinionated and clear path to implement payments:
+
+1. Define plans in code which sync to Stripe
+2. No manual webhook setup - the library handles webhooks and syncs Stripe data to your DB
+3. Simple APIs for subscriptions and credits
+4. Optional callbacks (`onSubscriptionCreated`, etc.) for custom logic
+
+## Setup
+
+### 1. Install
 
 ```bash
 npm install stripe-no-webhooks stripe
 ```
 
-## Setup
+Note: make sure you also have `.env` or `.env.local` in your project so it can save the generated secrets there.
 
-### 1. Create Stripe schema and tables
+### 2. Create tables where all Stripe data will be automatically synced
 
-**Option 1:** Run the migration command
+```bash
+npx stripe-no-webhooks migrate postgresql://[USER]:[PASSWORD]@[DB_URL]/postgres
+```
+
+### 3. Run `config` to generate files & webhook
 
 ```bash
-npx stripe-no-webhooks migrate postgresql://postgres.[USER]:[PASSWORD]@[DB_URL]/postgres
+npx stripe-no-webhooks config
 ```
 
-**Option 2:** Copy `stripe_schema.sql` and run the query manually
+This creates:
 
-### 2. Set up the webhook handler
+- `lib/billing.ts` - Billing instance (optional, for credits/subscriptions API)
+- `app/api/stripe/[...all]/route.ts` - HTTP handler
+- `billing.config.ts` - Your plans
 
-Create a webhook endpoint in your Next.js app:
+### 4. Connect your auth
 
-#### App Router (recommended)
+Open `app/api/stripe/[...all]/route.ts` and add your auth:
 
-```ts
-// app/api/stripe/webhook/route.ts
-import { createStripeWebhookHandler } from "stripe-no-webhooks";
+```typescript
+import { billing } from "@/lib/billing";
+import { auth } from "@clerk/nextjs/server"; // or your auth library
 
-const handler = createStripeWebhookHandler({
-  databaseUrl: process.env.DATABASE_URL!,
-  stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
-  stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
-  callbacks: {
-    onSubscriptionCreated: async (subscription) => {
-      // Called when a new subscription is created
-      console.log("New subscription:", subscription.id);
-      // e.g., send welcome email, provision resources, etc.
-    },
-    onSubscriptionCancelled: async (subscription) => {
-      // Called when a subscription is cancelled
-      console.log("Subscription cancelled:", subscription.id);
-      // e.g., send cancellation email, revoke access, etc.
-    },
+export const POST = billing.createHandler({
+  resolveUser: async () => {
+    const { userId } = await auth();
+    return userId ? { id: userId } : null;
   },
 });
-
-export const POST = handler;
 ```
 
-#### Pages Router
+**Simple alternative**: If you don't need credits/subscriptions API, skip `lib/billing.ts`:
 
-```ts
-// pages/api/stripe/webhook.ts
-import { createStripeWebhookHandler } from "stripe-no-webhooks";
-import type { NextApiRequest, NextApiResponse } from "next";
+```typescript
+import { createHandler } from "stripe-no-webhooks";
+import billingConfig from "@/billing.config";
 
-const handler = createStripeWebhookHandler({
-  databaseUrl: process.env.DATABASE_URL!,
-  stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
-  stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
-  callbacks: {
-    onSubscriptionCreated: async (subscription) => {
-      console.log("New subscription:", subscription.id);
-    },
-    onSubscriptionCancelled: async (subscription) => {
-      console.log("Subscription cancelled:", subscription.id);
-    },
+export const POST = createHandler({
+  billingConfig,
+  resolveUser: async () => {
+    const { userId } = await auth();
+    return userId ? { id: userId } : null;
   },
 });
+```
 
-// Disable body parsing, we need the raw body for webhook verification
-export const config = {
-  api: {
-    bodyParser: false,
+### 5. Create your plans
+
+```javascript
+// billing.config.ts
+import type { BillingConfig } from "stripe-no-webhooks";
+
+const billingConfig: BillingConfig = {
+  test: {
+    plans: [
+      {
+        name: "Premium",
+        description: "Access to all features",
+        price: [
+          { amount: 1000, currency: "usd", interval: "month" },
+          { amount: 10000, currency: "usd", interval: "year" },
+        ],
+        credits: {
+          api_calls: { allocation: 1000 },
+        },
+      },
+    ],
   },
 };
+export default billingConfig;
+```
 
-export default async function webhookHandler(
-  req: NextApiRequest,
-  res: NextApiResponse
-) {
-  if (req.method !== "POST") {
-    return res.status(405).json({ error: "Method not allowed" });
-  }
-
-  // Convert NextApiRequest to Request for the handler
-  const body = await new Promise<string>((resolve) => {
-    let data = "";
-    req.on("data", (chunk) => (data += chunk));
-    req.on("end", () => resolve(data));
-  });
-
-  const request = new Request(`https://${req.headers.host}${req.url}`, {
-    method: "POST",
-    headers: new Headers(req.headers as Record<string, string>),
-    body,
-  });
-
-  const response = await handler(request);
-  res.status(response.status).send(await response.text());
-}
+Run sync:
+
+```bash
+npx stripe-no-webhooks sync
 ```
 
-### 3. Configure Stripe webhook
+### 6. (optional) Write custom logic for subscriptions
 
-Run the config command to automatically create a webhook in your Stripe account:
+You probably want something to happen when a new user subscribes or a subscription cancels. Define callbacks when creating the `Billing` instance:
 
-```bash
-npx stripe-no-webhooks config
+```typescript
+// lib/billing.ts
+import { Billing } from "stripe-no-webhooks";
+import billingConfig from "../billing.config";
+import type { Stripe } from "stripe";
+
+export const billing = new Billing({
+  billingConfig,
+  callbacks: {
+    onSubscriptionCreated: async (subscription: Stripe.Subscription) => {
+      console.log("New subscription:", subscription.id);
+    },
+    onSubscriptionCancelled: async (subscription: Stripe.Subscription) => {
+      console.log("Subscription cancelled:", subscription.id);
+    },
+  },
+});
 ```
 
-This will:
+Supported callbacks:
 
-1. Ask for your Stripe Secret Key
-2. Ask for your site URL (defaults to `NEXT_PUBLIC_SITE_URL` if set)
-3. Create a webhook endpoint at `https://yoursite.com/api/stripe/webhook` listening to all events
-4. Automatically add `STRIPE_WEBHOOK_SECRET` to your `.env` files (if they exist)
+- `onSubscriptionCreated`
+- `onSubscriptionCancelled`
+- `onSubscriptionRenewed`
+- `onSubscriptionPlanChanged`
+- `onCreditsGranted`
+- `onCreditsRevoked`
+- `onTopUpCompleted`
+- `onAutoTopUpFailed`
+- `onCreditsLow`
 
-## Environment Variables
+### 7. (optional) Generate a pricing page
 
-```env
-DATABASE_URL=postgresql://user:pass@host:port/db
-STRIPE_SECRET_KEY=sk_test_...
-STRIPE_WEBHOOK_SECRET=whsec_...  # Output from `npx stripe-no-webhooks config`
+```bash
+npx stripe-no-webhooks generate pricing-page
 ```
 
-## What gets synced?
+This will create a `PricingPage` component in `@/components`. Feel free to edit styling manually or with AI.
 
-All Stripe webhook events are automatically synced to your PostgreSQL database in the `stripe` schema. This includes:
+It is ready-to-use with loading states, error handling, and styling. Import it whenever you want:
 
-- Customers
-- Subscriptions
-- Products
-- Prices
-- Invoices
-- Payment methods
-- And more...
+```tsx
+import { PricingPage } from "@/components/PricingPage";
+import billingConfig from "@/billing.config";
 
-You can query this data directly from your database without making API calls to Stripe.
+export default function Pricing() {
+  const plans = billingConfig.test?.plans || [];
+  return <PricingPage plans={plans} currentPlanId="free" />;
+}
+```
 
-## Callbacks
+### 8. (optional) Backfill data
 
-| Callback                  | Event                                                           | Description                               |
-| ------------------------- | --------------------------------------------------------------- | ----------------------------------------- |
-| `onSubscriptionCreated`   | `customer.subscription.created`                                 | Called when a new subscription is created |
-| `onSubscriptionCancelled` | `customer.subscription.deleted` or status changes to `canceled` | Called when a subscription is cancelled   |
+If you had data in Stripe before deploying `stripe-no-webhooks`, you can backfill your database by running:
 
-Both callbacks receive the full Stripe `Subscription` object.
+```bash
+npx stripe-no-webhooks backfill
+```