paddle-checkout-accelerator 2.1.0

package/dist/src/lib/billing/usage.js

@@ -0,0 +1,40 @@
+import { memoryBillingAdapter, } from "./adapters";
+import { plans } from "./plans";
+import { getSubscription } from "./subscriptions";
+let adapter = memoryBillingAdapter;
+export function setUsageAdapter(nextAdapter) {
+    adapter = nextAdapter;
+}
+function currentPeriod() {
+    const now = new Date();
+    return `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, "0")}`;
+}
+export async function getUsage(userId, key) {
+    return adapter.getUsage(userId, key, currentPeriod());
+}
+export async function getUsageLimit(userId) {
+    const subscription = await getSubscription(userId);
+    return plans[subscription.plan].monthlyLimit;
+}
+export async function canUse(userId, key) {
+    const [used, limit] = await Promise.all([
+        getUsage(userId, key),
+        getUsageLimit(userId),
+    ]);
+    return {
+        allowed: used < limit,
+        used,
+        limit,
+        remaining: Math.max(0, limit - used),
+    };
+}
+export async function incrementUsage(userId, key, amount = 1) {
+    return adapter.incrementUsage(userId, key, currentPeriod(), amount);
+}
+export async function requireUsage(userId, key) {
+    const usage = await canUse(userId, key);
+    if (!usage.allowed) {
+        throw new Error("Usage limit reached");
+    }
+    return usage;
+}

package/dist/src/lib/billing/webhook-sync.d.ts

@@ -0,0 +1,26 @@
+import type { PlanId } from "./plans";
+interface PaddleEvent {
+    event_type?: string;
+    data?: {
+        id?: string;
+        status?: string;
+        customer_id?: string;
+        custom_data?: {
+            userId?: string;
+            plan?: PlanId;
+        };
+        current_billing_period?: {
+            ends_at?: string;
+        };
+    };
+}
+export declare function syncPaddleEvent(event: PaddleEvent): Promise<{
+    synced: boolean;
+    reason: string;
+    type?: undefined;
+} | {
+    synced: boolean;
+    type: string;
+    reason?: undefined;
+}>;
+export {};

package/dist/src/lib/billing/webhook-sync.js

@@ -0,0 +1,39 @@
+import { upsertSubscription } from "./subscriptions";
+export async function syncPaddleEvent(event) {
+    const data = event.data;
+    const userId = data?.custom_data?.userId;
+    if (!userId) {
+        return {
+            synced: false,
+            reason: "missing userId in custom_data",
+        };
+    }
+    const plan = data?.custom_data?.plan ?? "starter";
+    if (event.event_type?.startsWith("subscription.")) {
+        await upsertSubscription({
+            userId,
+            plan,
+            status: data?.status === "active"
+                ? "active"
+                : data?.status === "trialing"
+                    ? "trialing"
+                    : data?.status === "paused"
+                        ? "paused"
+                        : data?.status === "canceled"
+                            ? "canceled"
+                            : "none",
+            paddleCustomerId: data?.customer_id,
+            paddleSubscriptionId: data?.id,
+            currentPeriodEnd: data?.current_billing_period
+                ?.ends_at,
+        });
+        return {
+            synced: true,
+            type: "subscription",
+        };
+    }
+    return {
+        synced: false,
+        reason: "unhandled event type",
+    };
+}

package/dist/src/lib/paddle/api.d.ts

@@ -0,0 +1 @@
+export declare function paddleApi<T>(path: string, options?: RequestInit): Promise<T>;

package/dist/src/lib/paddle/api.js

@@ -0,0 +1,21 @@
+const PADDLE_API_BASE = process.env.PADDLE_API_BASE ??
+    "https://api.paddle.com";
+export async function paddleApi(path, options = {}) {
+    const apiKey = process.env.PADDLE_API_KEY;
+    if (!apiKey) {
+        throw new Error("Missing PADDLE_API_KEY");
+    }
+    const response = await fetch(`${PADDLE_API_BASE}${path}`, {
+        ...options,
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            ...options.headers,
+        },
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Paddle API failed: ${response.status} ${text}`);
+    }
+    return response.json();
+}

package/dist/src/lib/paddle/client.d.ts

@@ -0,0 +1 @@
+export declare function getPaddle(): Promise<import("@paddle/paddle-js").Paddle | undefined>;

package/dist/src/lib/paddle/client.js

@@ -0,0 +1,13 @@
+import { initializePaddle } from "@paddle/paddle-js";
+let paddleInstance = null;
+export async function getPaddle() {
+    if (paddleInstance) {
+        return paddleInstance;
+    }
+    paddleInstance =
+        await initializePaddle({
+            token: process.env
+                .NEXT_PUBLIC_PADDLE_CLIENT_TOKEN,
+        });
+    return paddleInstance;
+}

package/dist/src/lib/paddle/customers.d.ts

@@ -0,0 +1,15 @@
+export interface PaddleCustomer {
+    id: string;
+    email?: string;
+    name?: string;
+    status?: string;
+}
+export interface PaddleCustomerListResponse {
+    data?: PaddleCustomer[];
+}
+export interface PaddleCustomerResponse {
+    data?: PaddleCustomer;
+}
+export declare function fetchPaddleCustomer(customerId: string): Promise<PaddleCustomerResponse>;
+export declare function findPaddleCustomersByEmail(email: string): Promise<PaddleCustomerListResponse>;
+export declare function findFirstPaddleCustomerByEmail(email: string): Promise<PaddleCustomer | null>;

package/dist/src/lib/paddle/customers.js

@@ -0,0 +1,14 @@
+import { paddleApi } from "./api";
+export async function fetchPaddleCustomer(customerId) {
+    return paddleApi(`/customers/${customerId}`);
+}
+export async function findPaddleCustomersByEmail(email) {
+    const params = new URLSearchParams({
+        email,
+    });
+    return paddleApi(`/customers?${params.toString()}`);
+}
+export async function findFirstPaddleCustomerByEmail(email) {
+    const response = await findPaddleCustomersByEmail(email);
+    return response.data?.[0] ?? null;
+}

package/dist/src/lib/paddle/events.d.ts

@@ -0,0 +1,10 @@
+export declare enum PaddleEventType {
+    TransactionCompleted = "transaction.completed",
+    TransactionPaid = "transaction.paid",
+    SubscriptionCreated = "subscription.created",
+    SubscriptionActivated = "subscription.activated",
+    SubscriptionUpdated = "subscription.updated",
+    SubscriptionCanceled = "subscription.canceled",
+    SubscriptionPaused = "subscription.paused",
+    CustomerCreated = "customer.created"
+}

package/dist/src/lib/paddle/events.js

@@ -0,0 +1,11 @@
+export var PaddleEventType;
+(function (PaddleEventType) {
+    PaddleEventType["TransactionCompleted"] = "transaction.completed";
+    PaddleEventType["TransactionPaid"] = "transaction.paid";
+    PaddleEventType["SubscriptionCreated"] = "subscription.created";
+    PaddleEventType["SubscriptionActivated"] = "subscription.activated";
+    PaddleEventType["SubscriptionUpdated"] = "subscription.updated";
+    PaddleEventType["SubscriptionCanceled"] = "subscription.canceled";
+    PaddleEventType["SubscriptionPaused"] = "subscription.paused";
+    PaddleEventType["CustomerCreated"] = "customer.created";
+})(PaddleEventType || (PaddleEventType = {}));

package/dist/src/lib/paddle/hooks.d.ts

@@ -0,0 +1,4 @@
+export declare function openCheckout(items: {
+    priceId: string;
+    quantity: number;
+}[]): Promise<void>;

package/dist/src/lib/paddle/hooks.js

@@ -0,0 +1,11 @@
+"use client";
+import { getPaddle } from "./client";
+export async function openCheckout(items) {
+    const paddle = await getPaddle();
+    if (!paddle) {
+        throw new Error("Paddle failed to initialize");
+    }
+    paddle.Checkout.open({
+        items,
+    });
+}

package/dist/src/lib/paddle/portal.d.ts

@@ -0,0 +1,8 @@
+export interface CreatePortalSessionOptions {
+    customerId: string;
+    returnUrl?: string;
+}
+export interface PortalSessionResult {
+    url: string;
+}
+export declare function createCustomerPortalSession({ customerId, returnUrl, }: CreatePortalSessionOptions): Promise<PortalSessionResult>;

package/dist/src/lib/paddle/portal.js

@@ -0,0 +1,28 @@
+export async function createCustomerPortalSession({ customerId, returnUrl, }) {
+    const apiKey = process.env.PADDLE_API_KEY;
+    if (!apiKey) {
+        throw new Error("Missing PADDLE_API_KEY");
+    }
+    const response = await fetch("https://api.paddle.com/customer-portal-sessions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            customer_id: customerId,
+            urls: returnUrl
+                ? { return_url: returnUrl }
+                : undefined,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error("Failed to create Paddle customer portal session");
+    }
+    const data = (await response.json());
+    const url = data.data?.urls?.general;
+    if (!url) {
+        throw new Error("Paddle portal URL missing from response");
+    }
+    return { url };
+}

package/dist/src/lib/paddle/subscriptions.d.ts

@@ -0,0 +1,20 @@
+export interface PaddleSubscription {
+    id: string;
+    status: string;
+    customer_id?: string;
+    current_billing_period?: {
+        ends_at?: string;
+    };
+    custom_data?: {
+        userId?: string;
+        plan?: "free" | "starter" | "pro" | "business";
+    };
+}
+export interface PaddleSubscriptionResponse {
+    data?: PaddleSubscription;
+}
+export interface PaddleSubscriptionListResponse {
+    data?: PaddleSubscription[];
+}
+export declare function fetchPaddleSubscription(subscriptionId: string): Promise<PaddleSubscriptionResponse>;
+export declare function fetchPaddleSubscriptionsForCustomer(customerId: string): Promise<PaddleSubscriptionListResponse>;

package/dist/src/lib/paddle/subscriptions.js

@@ -0,0 +1,10 @@
+import { paddleApi } from "./api";
+export async function fetchPaddleSubscription(subscriptionId) {
+    return paddleApi(`/subscriptions/${subscriptionId}`);
+}
+export async function fetchPaddleSubscriptionsForCustomer(customerId) {
+    const params = new URLSearchParams({
+        customer_id: customerId,
+    });
+    return paddleApi(`/subscriptions?${params.toString()}`);
+}

package/dist/src/lib/paddle/types.d.ts

@@ -0,0 +1,8 @@
+export interface CheckoutItem {
+    priceId: string;
+    quantity: number;
+}
+export interface OpenCheckoutOptions {
+    items: CheckoutItem[];
+    customerEmail?: string;
+}

package/dist/src/lib/paddle/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/paddle/webhook.d.ts

@@ -0,0 +1 @@
+export declare function verifyPaddleWebhook(rawBody: string, signature: string): Promise<unknown>;

package/dist/src/lib/paddle/webhook.js

@@ -0,0 +1,8 @@
+import { Webhook } from "svix";
+export async function verifyPaddleWebhook(rawBody, signature) {
+    const secret = process.env.PADDLE_WEBHOOK_SECRET;
+    const wh = new Webhook(secret);
+    return wh.verify(rawBody, {
+        "paddle-signature": signature,
+    });
+}

package/dist/src/lib/utils.d.ts

@@ -0,0 +1,2 @@
+import { type ClassValue } from "clsx";
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/src/lib/utils.js

@@ -0,0 +1,5 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}

package/docs/agency-use-case.md

@@ -0,0 +1,19 @@
+# Agency Use Case
+
+Build SaaS billing systems faster.
+
+## Functions
+
+requireSubscription()
+hasFeature()
+canUse()
+incrementUsage()
+syncPaddleEvent()
+
+## Ideal Clients
+
+AI SaaS
+Micro SaaS
+Developer Tools
+Membership Sites
+API Products

package/docs/quickstart.md

@@ -0,0 +1,24 @@
+# Paddle SaaS Billing Starter
+
+Quickstart documentation.
+
+## Core Usage
+
+import {
+  protectPlan,
+  protectFeature,
+  protectUsage
+} from "@/lib/billing/protection";
+
+await protectPlan(userId, "pro");
+await protectFeature(userId, "api_access");
+await protectUsage(userId, "ai_generation");
+
+## Webhook
+
+/api/paddle/webhook
+
+## Environment
+
+NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=
+PADDLE_WEBHOOK_SECRET=

package/docs/recipes/prisma/adapter.example.txt

@@ -0,0 +1,70 @@
+import type { BillingAdapter } from "@/lib/billing/adapters";
+import { prisma } from "./client.example";
+
+export const prismaBillingAdapter: BillingAdapter = {
+  async getSubscription(userId) {
+    return prisma.subscription.findUnique({
+      where: { userId },
+    });
+  },
+
+  async upsertSubscription(record) {
+    return prisma.subscription.upsert({
+      where: {
+        userId: record.userId,
+      },
+      create: record,
+      update: record,
+    });
+  },
+
+  async getUsage(
+    userId,
+    key,
+    period
+  ) {
+    const usage =
+      await prisma.usageEvent.findUnique({
+        where: {
+          userId_key_period: {
+            userId,
+            key,
+            period,
+          },
+        },
+      });
+
+    return usage?.count ?? 0;
+  },
+
+  async incrementUsage(
+    userId,
+    key,
+    period,
+    amount
+  ) {
+    const usage =
+      await prisma.usageEvent.upsert({
+        where: {
+          userId_key_period: {
+            userId,
+            key,
+            period,
+          },
+        },
+        create: {
+          userId,
+          key,
+          period,
+          count: amount,
+        },
+        update: {
+          count: {
+            increment: amount,
+          },
+        },
+      });
+
+    return usage.count;
+  },
+};

package/docs/recipes/prisma/client.example.txt

@@ -0,0 +1,4 @@
+import { PrismaClient } from "@prisma/client";
+
+export const prisma =
+  new PrismaClient();

package/docs/recipes/prisma/schema.prisma

@@ -0,0 +1,30 @@
+model Subscription {
+  id                     String   @id @default(cuid())
+  userId                 String   @unique
+
+  plan                   String
+  status                 String
+
+  paddleCustomerId       String?
+  paddleSubscriptionId   String?
+
+  currentPeriodEnd       DateTime?
+
+  createdAt              DateTime @default(now())
+  updatedAt              DateTime @updatedAt
+}
+
+model UsageEvent {
+  id        String   @id @default(cuid())
+
+  userId    String
+  key       String
+  period    String
+
+  count     Int      @default(0)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([userId, key, period])
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "paddle-checkout-accelerator",
+  "version": "2.1.0",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "test": "vitest run",
+    "build:package": "tsc -p tsconfig.package.json",
+    "prepack": "npm run build:package"
+  },
+  "dependencies": {
+    "@paddle/paddle-js": "^1.6.4",
+    "@radix-ui/react-dialog": "^1.1.16",
+    "@radix-ui/react-dropdown-menu": "^2.1.17",
+    "@radix-ui/react-scroll-area": "^1.2.11",
+    "@radix-ui/react-separator": "^1.1.9",
+    "@radix-ui/react-slot": "^1.2.5",
+    "@radix-ui/react-tabs": "^1.1.14",
+    "@radix-ui/react-tooltip": "^1.2.9",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "framer-motion": "^12.40.0",
+    "lucide-react": "^1.18.0",
+    "next": "16.2.9",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "svix": "^1.95.2",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.9",
+    "tailwindcss": "^4",
+    "typescript": "^5",
+    "vitest": "^4.1.8"
+  },
+  "type": "module",
+  "main": "./dist/package/index.js",
+  "types": "./dist/package/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/package/index.d.ts",
+      "import": "./dist/package/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs",
+    "recipes"
+  ]
+}

package/recipes/README.md

@@ -0,0 +1,20 @@
+# Recipes
+
+Copy-paste examples for real SaaS projects.
+
+## Next.js
+
+- protected-api-route.ts
+- server-page-gate.tsx
+- webhook-route.ts
+- custom-adapter.example.txt
+
+These recipes help agencies integrate Paddle billing into client projects quickly.
+
+## Prisma
+
+schema.prisma
+adapter.example.txt
+client.example.txt
+
+Provides a production-ready adapter example.

package/recipes/nextjs/app/billing.ts

@@ -0,0 +1,14 @@
+import {
+  configureBilling,
+  createPrismaBillingAdapter,
+} from "@namahlogisticspaddle-checkout-accelerator";
+
+import { prisma } from "@/lib/prisma";
+
+const adapter =
+  createPrismaBillingAdapter(prisma);
+
+export const billing =
+  configureBilling({
+    adapter,
+  });

package/recipes/nextjs/custom-adapter.ts

@@ -0,0 +1,26 @@
+import type { BillingAdapter } from "@/lib/billing/adapters";
+
+export const customBillingAdapter: BillingAdapter = {
+  async getSubscription(userId) {
+    // Replace with Prisma/Supabase query
+    console.log(userId);
+    return null;
+  },
+
+  async upsertSubscription(record) {
+    // Replace with Prisma/Supabase upsert
+    return record;
+  },
+
+  async getUsage(userId, key, period) {
+    // Replace with DB lookup
+    console.log(userId, key, period);
+    return 0;
+  },
+
+  async incrementUsage(userId, key, period, amount) {
+    // Replace with DB increment
+    console.log(userId, key, period, amount);
+    return amount;
+  },
+};

package/recipes/nextjs/protected-api-route.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+import { protectFeature, protectUsage } from "@/lib/billing/protection";
+
+export async function POST() {
+  const userId = "replace-with-your-auth-user-id";
+
+  try {
+    await protectFeature(userId, "api_access");
+    await protectUsage(userId, "ai_generation");
+
+    return NextResponse.json({
+      success: true,
+      message: "Paid feature executed",
+    });
+  } catch (err) {
+    return NextResponse.json(
+      {
+        success: false,
+        error:
+          err instanceof Error
+            ? err.message
+            : "Access denied",
+      },
+      { status: 403 }
+    );
+  }
+}

package/recipes/nextjs/server-page-gate.tsx

@@ -0,0 +1,18 @@
+import { redirect } from "next/navigation";
+import { requireSubscription } from "@/lib/billing/subscriptions";
+
+export default async function ProDashboardPage() {
+  const userId = "replace-with-your-auth-user-id";
+
+  try {
+    await requireSubscription(userId, "pro");
+  } catch {
+    redirect("/upgrade");
+  }
+
+  return (
+    <main>
+      <h1>Pro Dashboard</h1>
+    </main>
+  );
+}