paddle-checkout-accelerator 2.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Commercial License
+
+Copyright (c) NamahLogistics.
+
+This source code is proprietary. You may not copy, redistribute, resell, sublicense, or publish this code without written permission.
+
+License terms are granted separately to paying customers.

package/README.md

@@ -0,0 +1,388 @@
+# Paddle Checkout Accelerator
+
+Production-ready Paddle Billing infrastructure for Next.js SaaS applications.
+
+Stop rebuilding billing systems for every SaaS project.
+
+Paddle Checkout Accelerator provides checkout flows, webhook verification, subscription synchronization, entitlements, usage limits, customer repair tooling, team billing, and route protection out of the box.
+
+---
+
+# Why This Exists
+
+Every SaaS founder eventually rebuilds the same billing infrastructure:
+
+* Checkout flows
+* Subscription synchronization
+* Webhook processing
+* Feature gating
+* Usage limits
+* Customer portal access
+* Team seat management
+* Failed payment recovery
+* Customer repair tools
+
+Most teams spend days or weeks building and testing this infrastructure before they can focus on their actual product.
+
+Paddle Checkout Accelerator provides a reusable billing layer so developers can focus on shipping features instead of rebuilding billing.
+
+---
+
+# Features
+
+## Paddle Billing
+
+* Paddle Checkout Launcher
+* Paddle Webhook Verification
+* Subscription Synchronization
+* Customer Portal Sessions
+* Paddle Customer Lookup
+* Subscription Refresh Utilities
+* Subscription Repair Utilities
+
+## Access Control
+
+* Plan Protection
+* Feature Protection
+* Usage Protection
+* Entitlement Engine
+
+## Team Billing
+
+* Team Creation
+* Owner/Admin/Member Roles
+* Seat Limits by Plan
+* Seat Usage Tracking
+* Team Member Management
+
+## Billing Events
+
+* Subscription Timeline
+* Payment Events
+* Repair Events
+* Portal Events
+* Audit Trail Foundation
+
+## Developer Experience
+
+* Pluggable Billing Adapter
+* Memory Adapter
+* Prisma Adapter
+* Unified Billing Configuration
+* TypeScript Support
+* Vitest Test Suite
+
+---
+
+# Screenshots
+
+## Repair Failed Subscriptions
+
+Fix customer accounts when payment succeeds but access was never unlocked.
+
+![Customer Repair](screenshots/customer-repair.png)
+
+---
+
+## Protect Paid API Routes
+
+Verify plans, features, and usage limits before executing premium SaaS actions.
+
+![API Protection](screenshots/api-protection.png)
+
+---
+
+## SaaS Billing Dashboard
+
+Manage subscriptions, usage, invoices, and customer billing access.
+
+![Billing Dashboard](screenshots/billing-dashboard.png)
+
+---
+
+# Problems It Solves
+
+* User paid but account did not unlock
+* Webhook failed or arrived late
+* Need to verify active subscriptions
+* Need paid API route protection
+* Need feature-level access control
+* Need monthly usage limits
+* Need customer lookup by email
+* Need customer portal access
+* Need team seat management
+* Need a reusable billing layer across multiple SaaS products
+
+---
+
+# Installation
+
+```bash
+npm install @namahlogisticspaddle-checkout-accelerator
+```
+
+---
+
+# Environment Variables
+
+```env
+NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=
+PADDLE_API_KEY=
+PADDLE_WEBHOOK_SECRET=
+```
+
+---
+
+# One-File Billing Setup
+
+Create a single billing setup file.
+
+```ts
+import {
+  configureBilling,
+  createPrismaBillingAdapter,
+} from "@namahlogisticspaddle-checkout-accelerator";
+
+import { prisma } from "@/lib/prisma";
+
+const adapter =
+  createPrismaBillingAdapter(prisma);
+
+export const billing =
+  configureBilling({
+    adapter,
+  });
+```
+
+---
+
+# Core Usage
+
+## Protect Plans
+
+```ts
+await protectPlan(
+  userId,
+  "pro"
+);
+```
+
+## Protect Features
+
+```ts
+await protectFeature(
+  userId,
+  "api_access"
+);
+```
+
+## Protect Usage
+
+```ts
+await protectUsage(
+  userId,
+  "ai_generation"
+);
+```
+
+## Refresh Subscription
+
+```ts
+await refreshSubscriptionFromPaddle(
+  subscriptionId
+);
+```
+
+## Repair Customer Access
+
+```ts
+await repairSubscriptionByEmail(
+  email
+);
+```
+
+---
+
+# Team Billing
+
+Create teams:
+
+```ts
+await createTeam({
+  teamId: "team_1",
+  name: "Acme",
+  ownerId: userId,
+});
+```
+
+Add members:
+
+```ts
+await addTeamMember({
+  teamId: "team_1",
+  userId: "user_2",
+});
+```
+
+Check seat usage:
+
+```ts
+await getSeatUsage(
+  "team_1"
+);
+```
+
+---
+
+# Billing Events
+
+Record events:
+
+```ts
+await recordBillingEvent({
+  id: "evt_1",
+  userId,
+  type: "payment_succeeded",
+  createdAt:
+    new Date().toISOString(),
+});
+```
+
+Read timeline:
+
+```ts
+await getBillingEvents(
+  userId
+);
+```
+
+---
+
+# Included API Routes
+
+```txt
+/api/paddle/webhook
+/api/paddle/portal-session
+/api/paddle/refresh-subscription
+/api/paddle/repair-by-email
+/api/demo/protected-generation
+```
+
+---
+
+# Included Demo Pages
+
+```txt
+/demo/pricing
+/demo/upgrade
+/demo/dashboard
+/demo/api-protection
+/demo/customer-lookup
+/demo/customer-repair
+/demo/saas
+```
+
+---
+
+# Adapter Support
+
+## Included
+
+* Memory Adapter
+* Prisma Adapter
+
+## Planned
+
+* Supabase Adapter
+* PostgreSQL Adapter
+* Clerk Integration
+* Auth.js Integration
+* CLI Installer
+
+---
+
+# Verification
+
+```bash
+npm run test
+npm run lint
+npm run build
+npm run build:package
+```
+
+---
+
+# Test Coverage
+
+Current test suite covers:
+
+* Plan Protection
+* Feature Protection
+* Usage Limits
+* Team Billing
+* Billing Events
+
+---
+
+# Ideal For
+
+* AI SaaS
+* Developer Tools
+* API Products
+* Membership Platforms
+* Internal SaaS Platforms
+* B2B SaaS Products
+* Agencies Implementing Paddle Billing
+
+---
+
+# Roadmap
+
+## v3.x
+
+* Supabase Adapter
+* PostgreSQL Adapter
+* Expanded Event Tracking
+
+## v4.x
+
+* Clerk Integration
+* Auth.js Integration
+* Firebase Auth Integration
+
+## v5.x
+
+* CLI Installer
+
+```bash
+npx paddle-accelerator init
+```
+
+## v6.x
+
+* Hosted Configuration Dashboard
+
+## v7.x
+
+* Near One-Click Billing Setup
+
+---
+
+# Version History
+
+* v0.1.0 — Billing Engine
+* v0.2.0 — Paddle Sync + Repair Layer
+* v0.3.0 — Customer Lookup + Email Repair
+* v0.4.0 — Billing Test Suite
+* v0.4.1 — Release Cleanup
+* v1.0.0 — Production Release
+* v2.0.0 — Team Billing + Seat Limits
+* v2.1.0 — Installable Package + Prisma Adapter + Unified Configuration
+
+---
+
+# License
+
+Copyright © NamahLogistics.
+
+Commercial license. Redistribution, resale, sublicensing, or republication of the source code is prohibited without written permission.

package/dist/package/index.d.ts

@@ -0,0 +1,28 @@
+export * from "../src/components/paddle/UpgradeModal";
+export * from "../src/components/paddle/UsageMeter";
+export * from "../src/components/paddle/TrialBanner";
+export * from "../src/components/paddle/BillingHistory";
+export * from "../src/components/paddle/CustomerPortalButton";
+export * from "../src/components/paddle/SubscriptionCard";
+export * from "../src/components/paddle/gates/SubscriptionGate";
+export * from "../src/lib/paddle/hooks";
+export * from "../src/lib/paddle/client";
+export * from "../src/lib/paddle/types";
+export * from "../src/lib/paddle/webhook";
+export * from "../src/lib/billing/plans";
+export * from "../src/lib/billing/subscriptions";
+export * from "../src/lib/billing/entitlements";
+export * from "../src/lib/billing/usage";
+export * from "../src/lib/billing/webhook-sync";
+export * from "../src/lib/billing/adapters";
+export * from "../src/lib/billing/protection";
+export * from "../src/lib/billing/demo-seed";
+export * from "../src/lib/paddle/portal";
+export * from "../src/lib/paddle/api";
+export * from "../src/lib/paddle/subscriptions";
+export * from "../src/lib/billing/refresh";
+export * from "../src/lib/paddle/customers";
+export * from "../src/lib/billing/customer-repair";
+export * from "../src/lib/billing/teams";
+export * from "../src/lib/billing/events";
+export * from "../src/lib/billing/configure";

package/dist/package/index.js

@@ -0,0 +1,28 @@
+export * from "../src/components/paddle/UpgradeModal";
+export * from "../src/components/paddle/UsageMeter";
+export * from "../src/components/paddle/TrialBanner";
+export * from "../src/components/paddle/BillingHistory";
+export * from "../src/components/paddle/CustomerPortalButton";
+export * from "../src/components/paddle/SubscriptionCard";
+export * from "../src/components/paddle/gates/SubscriptionGate";
+export * from "../src/lib/paddle/hooks";
+export * from "../src/lib/paddle/client";
+export * from "../src/lib/paddle/types";
+export * from "../src/lib/paddle/webhook";
+export * from "../src/lib/billing/plans";
+export * from "../src/lib/billing/subscriptions";
+export * from "../src/lib/billing/entitlements";
+export * from "../src/lib/billing/usage";
+export * from "../src/lib/billing/webhook-sync";
+export * from "../src/lib/billing/adapters";
+export * from "../src/lib/billing/protection";
+export * from "../src/lib/billing/demo-seed";
+export * from "../src/lib/paddle/portal";
+export * from "../src/lib/paddle/api";
+export * from "../src/lib/paddle/subscriptions";
+export * from "../src/lib/billing/refresh";
+export * from "../src/lib/paddle/customers";
+export * from "../src/lib/billing/customer-repair";
+export * from "../src/lib/billing/teams";
+export * from "../src/lib/billing/events";
+export * from "../src/lib/billing/configure";

package/dist/src/components/paddle/BillingHistory.d.ts

@@ -0,0 +1 @@
+export declare function BillingHistory(): import("react").JSX.Element;

package/dist/src/components/paddle/BillingHistory.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const invoices = [
+    {
+        id: "INV-001",
+        amount: "$79",
+        status: "Paid",
+    },
+    {
+        id: "INV-002",
+        amount: "$79",
+        status: "Paid",
+    },
+];
+export function BillingHistory() {
+    return (_jsx("div", { className: "rounded-xl border", children: invoices.map((invoice) => (_jsxs("div", { className: "flex justify-between border-b p-4", children: [_jsx("div", { children: invoice.id }), _jsx("div", { children: invoice.amount }), _jsx("div", { children: invoice.status })] }, invoice.id))) }));
+}

package/dist/src/components/paddle/CustomerPortal.d.ts

@@ -0,0 +1 @@
+export default function CustomerPortal(): import("react").JSX.Element;

package/dist/src/components/paddle/CustomerPortal.js

@@ -0,0 +1,5 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export default function CustomerPortal() {
+    return (_jsxs("div", { className: "rounded-3xl border p-8", children: [_jsx("h2", { className: "text-3xl font-bold", children: "Customer Portal" }), _jsxs("div", { className: "mt-8 space-y-4", children: [_jsx("div", { className: "rounded-xl border p-4", children: "Current Plan: Pro" }), _jsx("div", { className: "rounded-xl border p-4", children: "Status: Active" }), _jsx("div", { className: "rounded-xl border p-4", children: "Renewal Date: July 1, 2026" }), _jsx("button", { className: "rounded-xl bg-black px-5 py-3 text-white", children: "Manage Subscription" })] })] }));
+}

package/dist/src/components/paddle/CustomerPortalButton.d.ts

@@ -0,0 +1 @@
+export declare function CustomerPortalButton(): import("react").JSX.Element;

package/dist/src/components/paddle/CustomerPortalButton.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+export function CustomerPortalButton() {
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    async function launchPortal() {
+        try {
+            setLoading(true);
+            setError(null);
+            const response = await fetch("/api/paddle/portal-session", { method: "POST" });
+            const data = (await response.json());
+            if (!response.ok || !data.success || !data.url) {
+                throw new Error(data.error ??
+                    "Unable to open billing portal");
+            }
+            window.location.href = data.url;
+        }
+        catch (err) {
+            setError(err instanceof Error
+                ? err.message
+                : "Unable to open billing portal");
+        }
+        finally {
+            setLoading(false);
+        }
+    }
+    return (_jsxs("div", { className: "space-y-3", children: [_jsx("button", { onClick: launchPortal, disabled: loading, className: "rounded-xl bg-black px-4 py-3 text-white disabled:opacity-60", children: loading
+                    ? "Opening Billing..."
+                    : "Manage Billing" }), error && (_jsx("div", { className: "rounded-xl border border-red-200 bg-red-50 p-3 text-sm text-red-700", children: error }))] }));
+}

package/dist/src/components/paddle/InlineCheckout.d.ts

@@ -0,0 +1,5 @@
+interface Props {
+    priceId: string;
+}
+export default function InlineCheckout({ priceId, }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/paddle/InlineCheckout.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+export default function InlineCheckout({ priceId, }) {
+    const [loading, setLoading] = useState(true);
+    useEffect(() => {
+        const timer = setTimeout(() => {
+            setLoading(false);
+        }, 1500);
+        return () => clearTimeout(timer);
+    }, []);
+    return (_jsx("div", { className: "rounded-3xl border bg-white p-6", children: loading ? (_jsxs("div", { className: "space-y-4 animate-pulse", children: [_jsx("div", { className: "h-10 rounded bg-gray-100" }), _jsx("div", { className: "h-10 rounded bg-gray-100" }), _jsx("div", { className: "h-40 rounded bg-gray-100" })] })) : (_jsxs("div", { children: [_jsx("div", { className: "mb-4 text-sm text-gray-500", children: "Paddle Inline Checkout" }), _jsx("div", { id: "paddle-inline-checkout", "data-price-id": priceId, className: "min-h-[500px] rounded-xl border" })] })) }));
+}

package/dist/src/components/paddle/PricingTable.d.ts

@@ -0,0 +1 @@
+export default function PricingTable(): import("react").JSX.Element;

package/dist/src/components/paddle/PricingTable.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Check } from "lucide-react";
+const plans = [
+    {
+        name: "Starter",
+        price: "$29",
+        features: [
+            "1 Project",
+            "Lifetime Updates",
+            "Source Code"
+        ]
+    },
+    {
+        name: "Pro",
+        price: "$79",
+        featured: true,
+        features: [
+            "Unlimited Projects",
+            "Premium Components",
+            "Priority Support"
+        ]
+    }
+];
+export default function PricingTable() {
+    return (_jsx("div", { className: "grid gap-8 md:grid-cols-2", children: plans.map((plan) => (_jsxs("div", { className: `rounded-3xl border p-8 ${plan.featured ? "ring-2 ring-black" : ""}`, children: [_jsx("h3", { className: "text-2xl font-bold", children: plan.name }), _jsx("div", { className: "mt-6 text-5xl font-bold", children: plan.price }), _jsx("ul", { className: "mt-8 space-y-4", children: plan.features.map((feature) => (_jsxs("li", { className: "flex gap-3", children: [_jsx(Check, { size: 18 }), feature] }, feature))) }), _jsx("button", { className: "mt-8 w-full rounded-xl bg-black py-3 text-white", children: "Buy Now" })] }, plan.name))) }));
+}

package/dist/src/components/paddle/SubscriptionCard.d.ts

@@ -0,0 +1,6 @@
+interface SubscriptionCardProps {
+    plan: string;
+    status: string;
+}
+export declare function SubscriptionCard({ plan, status, }: SubscriptionCardProps): import("react").JSX.Element;
+export {};

package/dist/src/components/paddle/SubscriptionCard.js

@@ -0,0 +1,5 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function SubscriptionCard({ plan, status, }) {
+    return (_jsxs("div", { className: "rounded-2xl border p-6", children: [_jsx("div", { className: "text-sm text-gray-500", children: "Current Plan" }), _jsx("div", { className: "mt-2 text-3xl font-bold", children: plan }), _jsxs("div", { className: "mt-4", children: ["Status: ", status] })] }));
+}

package/dist/src/components/paddle/TrialBanner.d.ts

@@ -0,0 +1,5 @@
+interface TrialBannerProps {
+    daysRemaining: number;
+}
+export declare function TrialBanner({ daysRemaining, }: TrialBannerProps): import("react").JSX.Element;
+export {};

package/dist/src/components/paddle/TrialBanner.js

@@ -0,0 +1,5 @@
+"use client";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+export function TrialBanner({ daysRemaining, }) {
+    return (_jsxs("div", { className: "rounded-xl border border-yellow-300 bg-yellow-50 p-4", children: ["Trial expires in", " ", _jsxs("strong", { children: [daysRemaining, " days"] }), "."] }));
+}

package/dist/src/components/paddle/UpgradeModal.d.ts

@@ -0,0 +1,11 @@
+interface UpgradeModalProps {
+    open: boolean;
+    onClose: () => void;
+    currentPlan: string;
+    targetPlan: string;
+    targetPriceId: string;
+    yearlySavings?: string;
+    onUpgradeSuccess?: (data: unknown) => void;
+}
+export declare function UpgradeModal({ open, onClose, currentPlan, targetPlan, targetPriceId, yearlySavings, onUpgradeSuccess, }: UpgradeModalProps): import("react").JSX.Element | null;
+export {};

package/dist/src/components/paddle/UpgradeModal.js

@@ -0,0 +1,35 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from "react";
+import { ArrowRight, Check, Loader2, X, } from "lucide-react";
+import { openCheckout } from "@/lib/paddle/hooks";
+export function UpgradeModal({ open, onClose, currentPlan, targetPlan, targetPriceId, yearlySavings, onUpgradeSuccess, }) {
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    if (!open)
+        return null;
+    async function handleUpgrade() {
+        try {
+            setLoading(true);
+            setError(null);
+            await openCheckout([
+                {
+                    priceId: targetPriceId,
+                    quantity: 1,
+                },
+            ]);
+            onUpgradeSuccess?.({
+                targetPlan,
+            });
+        }
+        catch (err) {
+            setError(err instanceof Error
+                ? err.message
+                : "Unable to launch checkout");
+        }
+        finally {
+            setLoading(false);
+        }
+    }
+    return (_jsx("div", { className: "fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4", children: _jsxs("div", { className: "w-full max-w-lg rounded-3xl border bg-white shadow-2xl", children: [_jsxs("div", { className: "flex items-center justify-between border-b p-6", children: [_jsxs("div", { children: [_jsx("h2", { className: "text-xl font-semibold", children: "Upgrade Plan" }), _jsx("p", { className: "mt-1 text-sm text-slate-500", children: "Unlock additional features" })] }), _jsx("button", { onClick: onClose, className: "rounded-lg p-2 hover:bg-slate-100", children: _jsx(X, { size: 18 }) })] }), _jsxs("div", { className: "p-6", children: [_jsx("div", { className: "rounded-2xl border p-5", children: _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("div", { children: [_jsx("div", { className: "text-sm text-slate-500", children: "Current" }), _jsx("div", { className: "mt-1 font-semibold", children: currentPlan })] }), _jsx(ArrowRight, { className: "text-slate-400", size: 20 }), _jsxs("div", { className: "text-right", children: [_jsx("div", { className: "text-sm text-slate-500", children: "Upgrade To" }), _jsx("div", { className: "mt-1 font-semibold", children: targetPlan })] })] }) }), _jsx("div", { className: "mt-6 rounded-2xl bg-slate-50 p-5", children: _jsxs("ul", { className: "space-y-3", children: [_jsxs("li", { className: "flex items-center gap-3", children: [_jsx(Check, { size: 16 }), "Unlimited projects"] }), _jsxs("li", { className: "flex items-center gap-3", children: [_jsx(Check, { size: 16 }), "Advanced billing"] }), _jsxs("li", { className: "flex items-center gap-3", children: [_jsx(Check, { size: 16 }), "Priority support"] }), _jsxs("li", { className: "flex items-center gap-3", children: [_jsx(Check, { size: 16 }), "Team access"] })] }) }), yearlySavings && (_jsxs("div", { className: "mt-4 rounded-xl border border-emerald-200 bg-emerald-50 p-3 text-sm", children: ["Save ", yearlySavings] })), error && (_jsx("div", { className: "mt-4 rounded-xl border border-red-200 bg-red-50 p-3 text-sm text-red-700", children: error })), _jsx("button", { onClick: handleUpgrade, disabled: loading, className: "mt-6 flex w-full items-center justify-center gap-2 rounded-2xl bg-black px-5 py-4 text-white transition hover:opacity-90 disabled:opacity-50", children: loading ? (_jsxs(_Fragment, { children: [_jsx(Loader2, { size: 18, className: "animate-spin" }), "Launching Checkout..."] })) : (_jsxs(_Fragment, { children: ["Upgrade Now", _jsx(ArrowRight, { size: 18 })] })) })] })] }) }));
+}

package/dist/src/components/paddle/UsageMeter.d.ts

@@ -0,0 +1,6 @@
+interface UsageMeterProps {
+    current: number;
+    limit: number;
+}
+export declare function UsageMeter({ current, limit, }: UsageMeterProps): import("react").JSX.Element;
+export {};

package/dist/src/components/paddle/UsageMeter.js

@@ -0,0 +1,8 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function UsageMeter({ current, limit, }) {
+    const percentage = Math.min(100, (current / limit) * 100);
+    return (_jsxs("div", { className: "rounded-xl border p-5", children: [_jsxs("div", { className: "flex justify-between", children: [_jsx("span", { children: "Usage" }), _jsxs("span", { children: [current, "/", limit] })] }), _jsx("div", { className: "mt-3 h-3 rounded-full bg-gray-100", children: _jsx("div", { className: "h-3 rounded-full bg-black", style: {
+                        width: `${percentage}%`,
+                    } }) })] }));
+}

package/dist/src/components/paddle/gates/SubscriptionGate.d.ts

@@ -0,0 +1,7 @@
+interface SubscriptionGateProps {
+    active: boolean;
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+}
+export declare function SubscriptionGate({ active, children, fallback, }: SubscriptionGateProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined>;
+export {};