shipd 0.1.3 → 0.2.0

package/features/payments/README.md

@@ -0,0 +1,375 @@
+# Payments Module - Integration Guide
+
+**Module Version:** 1.0.0  
+**Last Updated:** 2025-12-22  
+**Standalone:** ⚠️ Requires Auth + Database Modules
+
+---
+
+## Overview
+
+This module adds complete subscription management and payment processing using Polar.sh. It includes subscription management pages, billing interfaces, webhook handling, and success pages.
+
+**Key Features:**
+- Polar.sh subscription integration
+- Subscription management dashboard
+- Customer portal access
+- Webhook handling for subscription events
+- Payment success page
+- Subscription status tracking
+- Product and pricing management
+
+---
+
+## Files Added
+
+### Pages/Routes
+- `app/dashboard/payment/page.tsx` - Payment and subscription management page
+- `app/success/page.tsx` - Success page after payment completion
+- `app/api/subscription/route.ts` - Subscription API endpoint
+
+### Components
+- `app/dashboard/payment/_components/manage-subscription.tsx` - Subscription management component
+
+### Utilities/Libraries
+- `lib/subscription.ts` - Subscription utilities and helpers
+- `lib/polar-products.ts` - Polar product fetching utilities
+- `payments-schema.ts` - Subscription table schema (merged into db/schema.ts)
+
+---
+
+## Dependencies
+
+### Package Dependencies
+The following packages will be added to `package.json`:
+- `@polar-sh/sdk@^0.42.1` - Polar.sh SDK
+
+### Required Modules
+- **Auth Module** - Payments requires authentication
+- **Database Module** - Payments requires database for subscription storage
+
+### Included Components
+This module uses UI components from the base package:
+- ✅ `components/ui/button.tsx` - For action buttons
+- ✅ `components/ui/card.tsx` - For subscription cards
+- ✅ `components/ui/badge.tsx` - For status badges
+
+---
+
+## Environment Variables
+
+Add these to your `.env.local`:
+
+```env
+# Payments (Polar.sh)
+POLAR_ACCESS_TOKEN="your-polar-access-token"
+POLAR_WEBHOOK_SECRET="your-webhook-secret"
+POLAR_SUCCESS_URL="success"  # Path to success page (e.g., "success")
+NEXT_PUBLIC_STARTER_TIER="your-product-id"  # Product ID for starter tier
+NEXT_PUBLIC_STARTER_SLUG="starter"  # Product slug
+NEXT_PUBLIC_APP_URL="http://localhost:3000"  # Your app URL (for webhooks)
+```
+
+**Required Variables:**
+- `POLAR_ACCESS_TOKEN` - Your Polar.sh API access token
+- `POLAR_WEBHOOK_SECRET` - Secret for webhook signature verification
+- `NEXT_PUBLIC_STARTER_TIER` - Product ID from Polar.sh dashboard
+- `NEXT_PUBLIC_STARTER_SLUG` - Product slug
+- `NEXT_PUBLIC_APP_URL` - Your application URL (for webhook callbacks)
+
+**Optional Variables:**
+- `POLAR_SUCCESS_URL` - Custom success page path (defaults to "success")
+
+**Where to get them:**
+- **Polar.sh Dashboard**: [polar.sh](https://polar.sh) - Create account and products
+- Get access token from API settings
+- Create webhook secret for signature verification
+- Create products and get product IDs
+
+---
+
+## Manual Integration Steps
+
+If you're appending this module to an existing project, follow these steps:
+
+### Step 1: Install Dependencies
+
+```bash
+npm install
+# or
+pnpm install
+# or
+yarn install
+```
+
+The append command automatically adds missing dependencies to `package.json`, but you need to install them.
+
+### Step 2: Add Environment Variables
+
+1. Copy `.env.example` to `.env.local` (if not exists)
+2. Add the required environment variables listed above
+3. Get your Polar.sh credentials from the [Polar.sh dashboard](https://polar.sh)
+
+### Step 3: Update Database Schema
+
+The payments module adds a subscription table. If you have the database module installed, the schema will be merged automatically. Otherwise:
+
+1. Add the subscription table to your `db/schema.ts`:
+   ```typescript
+   // Import from payments-schema.ts or copy the table definition
+   export { subscription } from '@/payments-schema';
+   ```
+
+2. Generate and run migrations:
+   ```bash
+   npm run db:generate
+   npm run db:push
+   ```
+
+### Step 4: Update Auth Configuration
+
+The payments module integrates with the auth module's Polar webhook handling. The auth module already includes webhook code, but you need to ensure:
+
+1. `lib/auth.ts` includes Polar integration (already done if auth module is installed)
+2. Webhook endpoint is accessible at `/api/auth/callback/polar`
+3. Webhook secret matches your Polar.sh configuration
+
+### Step 5: Verify Installation
+
+1. Start your dev server: `npm run dev`
+2. Visit `http://localhost:3000/dashboard/payment` to see subscription management
+3. Visit `http://localhost:3000/success` to see the success page
+4. Test the subscription API: `GET /api/subscription`
+
+---
+
+## Usage Examples
+
+### Checking Subscription Status
+
+```typescript
+import { getSubscriptionDetails, hasActiveSubscription } from "@/lib/subscription";
+
+// Get full subscription details
+const details = await getSubscriptionDetails();
+if (details.hasSubscription && details.subscription) {
+  console.log("Status:", details.subscription.status);
+  console.log("Amount:", details.subscription.amount);
+}
+
+// Quick check for active subscription
+const isActive = await hasActiveSubscription();
+```
+
+### Opening Customer Portal
+
+```typescript
+"use client";
+
+import { authClient } from "@/lib/auth-client";
+
+export function ManageSubscriptionButton() {
+  const handleOpenPortal = async () => {
+    try {
+      await authClient.customer.portal();
+    } catch (error) {
+      console.error("Failed to open portal:", error);
+    }
+  };
+
+  return <button onClick={handleOpenPortal}>Manage Subscription</button>;
+}
+```
+
+### Creating Checkout Session
+
+```typescript
+"use client";
+
+import { authClient } from "@/lib/auth-client";
+
+export function SubscribeButton({ productId }: { productId: string }) {
+  const handleSubscribe = async () => {
+    try {
+      await authClient.checkout({
+        productId,
+        successUrl: `${window.location.origin}/success`,
+      });
+    } catch (error) {
+      console.error("Checkout failed:", error);
+    }
+  };
+
+  return <button onClick={handleSubscribe}>Subscribe</button>;
+}
+```
+
+---
+
+## Customization
+
+### Styling
+- Payment pages use Tailwind CSS classes
+- Customize colors in `tailwind.config.ts`
+- Modify page layouts in `app/dashboard/payment/page.tsx`
+
+### Configuration
+- Product IDs are configured via environment variables
+- Webhook handling is in `lib/auth.ts` (auth module)
+- Customize success page in `app/success/page.tsx`
+
+### Subscription Management
+- Customize subscription display in `app/dashboard/payment/page.tsx`
+- Add custom subscription actions in `_components/manage-subscription.tsx`
+
+---
+
+## Integration Points
+
+### Files That May Need Manual Updates
+
+**lib/auth.ts** (if auth module installed):
+- Polar webhook handling is already included
+- Ensure webhook secret matches your Polar.sh configuration
+
+**db/schema.ts** (if database module installed):
+- Subscription table will be automatically merged
+- If manual merge needed, import from `payments-schema.ts`
+
+**Middleware** (if auth module installed):
+- No changes needed - payments uses existing auth protection
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue:** "Subscription table not found" error
+**Solution:**
+- Ensure database module is installed
+- Run `npm run db:push` to create tables
+- Verify subscription table exists in `db/schema.ts`
+
+**Issue:** Webhooks not working
+**Solution:**
+- Verify `POLAR_WEBHOOK_SECRET` matches Polar.sh dashboard
+- Check webhook URL is correct: `https://yourdomain.com/api/auth/callback/polar`
+- Ensure webhook events are enabled in Polar.sh dashboard
+
+**Issue:** "POLAR_ACCESS_TOKEN is required"
+**Solution:**
+- Add `POLAR_ACCESS_TOKEN` to `.env.local`
+- Get token from Polar.sh API settings
+- Restart dev server after adding env vars
+
+**Issue:** Checkout not redirecting
+**Solution:**
+- Verify `NEXT_PUBLIC_APP_URL` is set correctly
+- Check `POLAR_SUCCESS_URL` matches your success page path
+- Ensure product IDs are correct
+
+---
+
+## Next Steps
+
+After installing this module:
+
+1. Set up Polar.sh account and create products
+2. Configure environment variables
+3. Run database migrations
+4. Test checkout flow
+5. Configure webhooks in Polar.sh dashboard
+6. Customize success page
+7. Add pricing page (optional - can use marketing landing pricing section)
+
+---
+
+## Related Modules
+
+This module requires:
+- **Auth Module** - For user authentication and webhook handling
+- **Database Module** - For subscription storage
+
+This module works well with:
+- **Email Module** - For subscription confirmation emails
+- **Marketing Landing Module** - For pricing page display
+
+---
+
+## Module Status
+
+✅ **Core Files Included** - All payment pages and utilities  
+⚠️ **Requires Auth + Database** - Must be installed first  
+✅ **Webhook Integration** - Works with auth module's webhook handler  
+✅ **Well Documented** - Comprehensive integration guide
+
+---
+
+## AI Integration Prompt
+
+**For AI Assistants:** Use this prompt to understand and integrate the Payments module into an existing Next.js application.
+
+```
+The Payments module has been appended to this Next.js project. Your task is to ensure it's properly integrated and functional.
+
+**Installed Packages:**
+- @polar-sh/sdk@^0.42.1 - Polar.sh SDK for subscription management
+
+**Files Added:**
+- app/dashboard/payment/page.tsx - Subscription management page
+- app/dashboard/payment/_components/manage-subscription.tsx - Subscription management component
+- app/success/page.tsx - Checkout success page
+- app/api/subscription/route.ts - API route for fetching subscription details
+- lib/subscription.ts - Utilities for subscription operations
+- lib/polar-products.ts - Utilities for fetching Polar products
+- payments-schema.ts - Drizzle schema for subscription table
+
+**Schema Table Added to db/schema.ts:**
+- subscription - Subscription records with status, billing info, and user linkage
+
+**Environment Variables Required:**
+- POLAR_ACCESS_TOKEN - Polar.sh API access token
+- POLAR_SUCCESS_URL - Success page path (e.g., "success")
+- POLAR_WEBHOOK_SECRET - Webhook secret for verifying Polar webhooks
+- NEXT_PUBLIC_STARTER_TIER - Polar product ID for starter tier
+- NEXT_PUBLIC_STARTER_SLUG - Polar organization slug
+- NEXT_PUBLIC_APP_URL - Application URL (e.g., http://localhost:3000)
+- DATABASE_URL - Required (from database module)
+- BETTER_AUTH_SECRET - Required (from auth module)
+
+**Integration Steps:**
+1. Verify auth and database modules are installed (payments requires both)
+2. Check that subscription table was merged into db/schema.ts
+3. Verify lib/auth.ts has webhook handler for Polar subscription events
+4. Ensure app/api/subscription/route.ts is protected (requires authentication)
+5. Check that app/success/page.tsx exists for checkout redirects
+6. Verify environment variables are set in .env.local
+7. Run database migrations: npm run db:push (to create subscription table)
+
+**Key Integration Points:**
+- Webhook handling: lib/auth.ts contains onWebhook handler for Polar subscription events
+- Subscription table: Automatically merged into db/schema.ts during append
+- User linkage: subscription.userId references user.id from auth module
+- API routes: app/api/subscription/route.ts fetches subscription for authenticated user
+- Checkout flow: Users redirected to /success after successful checkout
+- Dynamic imports: auth.ts dynamically imports subscription table (only if payments installed)
+
+**Dependencies:**
+- REQUIRES: Auth module (for user authentication and webhook handling)
+- REQUIRES: Database module (for subscription storage)
+- OPTIONAL: Email module (for subscription confirmation emails)
+
+**Common Issues to Check:**
+- If "subscription is not exported" error: Check that subscription table was merged into db/schema.ts
+- If webhooks not working: Verify POLAR_WEBHOOK_SECRET matches Polar dashboard
+- If checkout fails: Check NEXT_PUBLIC_STARTER_TIER and NEXT_PUBLIC_STARTER_SLUG are correct
+- If subscription not showing: Ensure user is authenticated and subscription exists in database
+
+**Next Steps After Integration:**
+- Set up Polar.sh account and create products
+- Configure webhook URL in Polar dashboard: https://yourdomain.com/api/auth/callback/polar
+- Test checkout flow: Visit /dashboard/payment and subscribe
+- Verify webhook events are received and subscription table is updated
+- Customize success page at app/success/page.tsx
+```

package/features/payments/app/api/subscription/route.ts

@@ -0,0 +1,25 @@
+import { auth } from "@/lib/auth";
+import { getSubscriptionDetails } from "@/lib/subscription";
+import { headers } from "next/headers";
+import { NextResponse } from "next/server";
+
+export async function GET() {
+  try {
+    const result = await auth.api.getSession({
+      headers: await headers(),
+    });
+
+    if (!result?.session?.userId) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    const subscriptionDetails = await getSubscriptionDetails();
+    return NextResponse.json(subscriptionDetails);
+  } catch (error) {
+    console.error("Error fetching subscription details:", error);
+    return NextResponse.json(
+      { error: "Failed to fetch subscription details" },
+      { status: 500 }
+    );
+  }
+}

package/features/payments/app/dashboard/payment/_components/manage-subscription.tsx

@@ -0,0 +1,22 @@
+"use client";
+import { Button } from "@/components/ui/button";
+import { ExternalLink } from "lucide-react";
+import { authClient } from "@/lib/auth-client";
+
+export default function ManageSubscription() {
+  return (
+    <Button
+      variant="outline"
+      onClick={async () => {
+        try {
+          await authClient.customer.portal();
+        } catch (error) {
+          console.error("Failed to open customer portal:", error);
+        }
+      }}
+    >
+      <ExternalLink className="h-4 w-4 mr-2" />
+      Manage Subscription
+    </Button>
+  );
+}

package/features/payments/app/dashboard/payment/page.tsx

@@ -0,0 +1,126 @@
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { getSubscriptionDetails } from "@/lib/subscription";
+import Link from "next/link";
+import ManageSubscription from "./_components/manage-subscription";
+
+export default async function PaymentPage() {
+  const subscriptionDetails = await getSubscriptionDetails();
+
+  return (
+    <div>
+      <div className="p-6 space-y-4">
+        <div className="relative min-h-screen">
+          {!subscriptionDetails.hasSubscription ||
+          subscriptionDetails.subscription?.status !== "active" ? (
+            <>
+              <div className="absolute inset-0 z-10 rounded-lg flex items-center justify-center">
+                <div className="bg-white dark:bg-gray-900 p-8 rounded-lg shadow-lg text-center max-w-md">
+                  <h3 className="text-xl font-semibold mb-2">
+                    Subscription Required
+                  </h3>
+                  <p className="text-muted-foreground mb-4">
+                    You need an active subscription to access payment management
+                    features.
+                  </p>
+                  <Link href="/pricing">
+                    <Button>Subscribe Now</Button>
+                  </Link>
+                </div>
+              </div>
+              <div className="blur-sm pointer-events-none">
+                <Card>
+                  <CardHeader>
+                    <CardTitle>Payment Management</CardTitle>
+                    <CardDescription>
+                      Manage your billing and payment methods
+                    </CardDescription>
+                  </CardHeader>
+                  <CardContent className="space-y-4">
+                    <div className="grid grid-cols-2 gap-4">
+                      <div>
+                        <p className="text-sm font-medium text-muted-foreground">
+                          Current Plan
+                        </p>
+                        <p className="text-md">Pro Plan</p>
+                      </div>
+                      <div>
+                        <p className="text-sm font-medium text-muted-foreground">
+                          Billing Status
+                        </p>
+                        <p className="text-md">Active</p>
+                      </div>
+                    </div>
+                  </CardContent>
+                </Card>
+              </div>
+            </>
+          ) : (
+            <Card>
+              <CardHeader>
+                <CardTitle>Subscription Details</CardTitle>
+                <CardDescription>
+                  Your current subscription information
+                </CardDescription>
+              </CardHeader>
+              <CardContent className="space-y-4">
+                <div className="grid grid-cols-2 gap-4">
+                  <div>
+                    <p className="text-sm font-semibold text-muted-foreground">
+                      Status
+                    </p>
+                    <p className="text-md capitalize">
+                      {subscriptionDetails.subscription.status}
+                    </p>
+                  </div>
+                  <div>
+                    <p className="text-sm font-semibold text-muted-foreground">
+                      Amount
+                    </p>
+                    <p className="text-md">
+                      {subscriptionDetails.subscription.amount / 100}{" "}
+                      {subscriptionDetails.subscription.currency.toUpperCase()}
+                    </p>
+                  </div>
+                  <div>
+                    <p className="text-sm font-semibold text-muted-foreground">
+                      Billing Interval
+                    </p>
+                    <p className="text-md capitalize">
+                      {subscriptionDetails.subscription.recurringInterval}
+                    </p>
+                  </div>
+                  <div>
+                    <p className="text-sm font-semibold text-muted-foreground">
+                      Current Period End
+                    </p>
+                    <p className="text-md">
+                      {new Date(
+                        subscriptionDetails.subscription.currentPeriodEnd,
+                      ).toLocaleDateString()}
+                    </p>
+                  </div>
+                </div>
+                {subscriptionDetails.subscription.cancelAtPeriodEnd && (
+                  <div className="p-4 bg-yellow-50 border border-yellow-200 rounded-lg">
+                    <p className="text-sm text-yellow-800">
+                      Your subscription will cancel at the end of the current
+                      billing period.
+                    </p>
+                  </div>
+                )}
+                <ManageSubscription />
+              </CardContent>
+            </Card>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/features/payments/app/success/page.tsx

@@ -0,0 +1,123 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { CheckCircle2, Terminal, BookOpen, Zap } from "lucide-react";
+import { useRouter } from "next/navigation";
+import Link from "next/link";
+
+export default function SuccessPage() {
+  const router = useRouter();
+
+  return (
+    <div className="min-h-screen bg-black flex items-center justify-center p-6">
+      <Card className="bg-[#0a0a0a] border-[#2a2a2a] max-w-2xl w-full">
+        <CardContent className="p-12">
+          {/* Success Icon */}
+          <div className="w-20 h-20 bg-green-500/10 rounded-full flex items-center justify-center mx-auto mb-6">
+            <CheckCircle2 className="w-12 h-12 text-green-400" />
+          </div>
+
+          {/* Success Message */}
+          <div className="text-center mb-8">
+            <h1 className="text-3xl font-bold text-white mb-3">
+              Welcome! 🎉
+            </h1>
+            <p className="text-gray-400 text-lg">
+              Your subscription is now active. Let&apos;s get you started building your SaaS.
+            </p>
+          </div>
+
+          {/* Next Steps */}
+          <div className="space-y-6 mb-8">
+            <h2 className="text-xl font-semibold text-white">Next Steps</h2>
+
+            {/* Step 1 */}
+            <div className="flex gap-4">
+              <div className="w-8 h-8 rounded-full bg-[#ff5722] flex items-center justify-center text-white text-sm font-semibold flex-shrink-0">
+                1
+              </div>
+              <div className="flex-1">
+                <h3 className="text-white font-semibold mb-1">Authenticate the CLI</h3>
+                <p className="text-gray-400 text-sm mb-2">
+                  Run this command in your terminal to authenticate:
+                </p>
+                <div className="bg-black/70 p-3 rounded-lg border border-[#2a2a2a]">
+                  <code className="text-[#ff5722] font-mono text-sm">
+                    npx your-cli login
+                  </code>
+                </div>
+              </div>
+            </div>
+
+            {/* Step 2 */}
+            <div className="flex gap-4">
+              <div className="w-8 h-8 rounded-full bg-[#ff5722] flex items-center justify-center text-white text-sm font-semibold flex-shrink-0">
+                2
+              </div>
+              <div className="flex-1">
+                <h3 className="text-white font-semibold mb-1">Create your first project</h3>
+                <p className="text-gray-400 text-sm mb-2">
+                  Generate a complete SaaS application:
+                </p>
+                <div className="bg-black/70 p-3 rounded-lg border border-[#2a2a2a]">
+                  <code className="text-[#ff5722] font-mono text-sm">
+                    npx your-cli init my-app
+                  </code>
+                </div>
+              </div>
+            </div>
+
+            {/* Step 3 */}
+            <div className="flex gap-4">
+              <div className="w-8 h-8 rounded-full bg-[#ff5722] flex items-center justify-center text-white text-sm font-semibold flex-shrink-0">
+                3
+              </div>
+              <div className="flex-1">
+                <h3 className="text-white font-semibold mb-1">Start building</h3>
+                <p className="text-gray-400 text-sm">
+                  Your project includes authentication, billing, dashboard, and more - all ready to customize and deploy.
+                </p>
+              </div>
+            </div>
+          </div>
+
+          {/* Action Buttons */}
+          <div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
+            <Button
+              onClick={() => router.push("/dashboard")}
+              className="w-full bg-[#ff5722] hover:bg-[#d84315]"
+            >
+              <Zap className="w-4 h-4 mr-2" />
+              Go to Dashboard
+            </Button>
+            <Link href="/dashboard/cli" className="w-full">
+              <Button variant="outline" className="w-full border-[#2a2a2a] hover:bg-[#1a1a1a]">
+                <Terminal className="w-4 h-4 mr-2" />
+                CLI Guide
+              </Button>
+            </Link>
+            <Link href="/docs" className="w-full">
+              <Button variant="outline" className="w-full border-[#2a2a2a] hover:bg-[#1a1a1a]">
+                <BookOpen className="w-4 h-4 mr-2" />
+                Documentation
+              </Button>
+            </Link>
+          </div>
+
+          {/* Help Section */}
+          <div className="mt-8 pt-8 border-t border-[#2a2a2a] text-center">
+            <p className="text-gray-400 text-sm mb-2">
+              Need help getting started?
+            </p>
+            <Link href="mailto:support@yourdomain.com">
+              <Button variant="link" className="text-[#ff5722] hover:text-[#d84315]">
+                Contact Support
+              </Button>
+            </Link>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}