shipd 0.1.3 → 0.1.4

package/features/analytics/feature.config.json

@@ -0,0 +1,20 @@
+{
+  "name": "analytics",
+  "version": "1.0.0",
+  "description": "PostHog analytics integration with event tracking and feature flags",
+  "dependencies": {
+    "posthog-js": "^1.248.1",
+    "posthog-node": "^4.18.0"
+  },
+  "devDependencies": {},
+  "envVars": [
+    "NEXT_PUBLIC_POSTHOG_KEY",
+    "NEXT_PUBLIC_POSTHOG_HOST"
+  ],
+  "files": [
+    "lib/posthog.ts"
+  ],
+  "requires": [],
+  "conflicts": []
+}
+

package/features/analytics/lib/posthog.ts

@@ -0,0 +1,36 @@
+'use client';
+
+import posthog from 'posthog-js';
+import { PostHogProvider } from 'posthog-js/react';
+import { useEffect } from 'react';
+
+if (typeof window !== 'undefined') {
+  const posthogKey = process.env.NEXT_PUBLIC_POSTHOG_KEY;
+  const posthogHost = process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://app.posthog.com';
+
+  if (posthogKey) {
+    posthog.init(posthogKey, {
+      api_host: posthogHost,
+      person_profiles: 'identified_only', // or 'always' to create profiles for anonymous users as well
+    });
+  }
+}
+
+export function PostHogProviderWrapper({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    // Track pageviews
+    const handleRouteChange = () => {
+      posthog?.capture('$pageview');
+    };
+
+    // Track initial pageview
+    handleRouteChange();
+
+    return () => {
+      // Cleanup if needed
+    };
+  }, []);
+
+  return <PostHogProvider client={posthog}>{children}</PostHogProvider>;
+}
+

package/features/auth/README.md

@@ -0,0 +1,336 @@
+# Authentication Module - Integration Guide
+
+**Module Version:** 1.0.0  
+**Last Updated:** 2025-12-22  
+**Standalone:** ⚠️ Requires Database Module
+
+---
+
+## Overview
+
+This module adds complete authentication functionality to your Next.js application using Better Auth. It includes email/password authentication, Google OAuth, session management, and route protection.
+
+**Key Features:**
+- Email/password authentication
+- Google OAuth integration
+- Session management with secure cookies
+- Password reset functionality
+- Protected route middleware
+- User profile management
+- Optional Polar.sh subscription integration
+
+---
+
+## Files Added
+
+### Pages/Routes
+- `app/sign-in/page.tsx` - Sign in page with email/password and Google OAuth
+- `app/sign-up/page.tsx` - Sign up page with email/password and Google OAuth
+- `app/api/auth/[...all]/route.ts` - Better Auth API route handler
+
+### Utilities/Libraries
+- `lib/auth.ts` - Better Auth server configuration
+- `lib/auth-client.ts` - Better Auth client configuration
+- `auth-schema.ts` - Drizzle ORM schema for auth tables (user, session, account, verification)
+
+### Middleware
+- `middleware.patch.ts` - Middleware logic for route protection (will be merged into base middleware)
+
+---
+
+## Dependencies
+
+### Package Dependencies
+The following packages will be added to `package.json`:
+- `better-auth@^1.0.0` - Core authentication library
+- `@polar-sh/better-auth@^1.0.0` - Polar.sh integration for Better Auth (optional)
+
+### Required Modules
+- **Database Module** - Auth requires database for user/session storage
+- **Email Module** (optional) - For password reset emails (works without it, but emails won't send)
+
+### Included Components
+This module uses UI components from the base package:
+- ✅ `components/ui/button.tsx` - For form buttons
+- ✅ `components/ui/card.tsx` - For sign-in/sign-up cards
+- ✅ `components/ui/input.tsx` - For form inputs
+- ✅ `components/ui/label.tsx` - For form labels
+
+---
+
+## Environment Variables
+
+Add these to your `.env.local`:
+
+```env
+# Authentication
+BETTER_AUTH_SECRET="your-secret-key-here"  # Generate with: openssl rand -base64 32
+NEXT_PUBLIC_APP_URL="http://localhost:3000"
+
+# Google OAuth (optional but recommended)
+GOOGLE_CLIENT_ID="your-google-client-id"
+GOOGLE_CLIENT_SECRET="your-google-client-secret"
+```
+
+**Required Variables:**
+- `BETTER_AUTH_SECRET` - Secret key for signing tokens (generate a secure random string)
+- `NEXT_PUBLIC_APP_URL` - Your application URL (used for OAuth callbacks)
+
+**Optional Variables:**
+- `GOOGLE_CLIENT_ID` - Google OAuth client ID (get from [Google Cloud Console](https://console.cloud.google.com/))
+- `GOOGLE_CLIENT_SECRET` - Google OAuth client secret
+
+---
+
+## 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. Generate `BETTER_AUTH_SECRET`:
+   ```bash
+   openssl rand -base64 32
+   ```
+4. Set up Google OAuth (optional):
+   - Go to [Google Cloud Console](https://console.cloud.google.com/)
+   - Create OAuth 2.0 credentials
+   - Add authorized redirect URI: `http://localhost:3000/api/auth/callback/google`
+
+### Step 3: Update Database Schema
+
+The auth module requires database tables. If you have the database module installed, the schema will be merged automatically. Otherwise, you need to:
+
+1. Add the auth schema to your `db/schema.ts`:
+   ```typescript
+   // Import from auth-schema.ts or copy the table definitions
+   export { user, session, account, verification } from '@/auth-schema';
+   ```
+
+2. Generate and run migrations:
+   ```bash
+   npm run db:generate
+   npm run db:push
+   ```
+
+### Step 4: Update Middleware
+
+The auth module includes middleware for route protection. Update your `middleware.ts`:
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+import { getSessionCookie } from "better-auth/cookies";
+
+export async function middleware(request: NextRequest) {
+  const sessionCookie = getSessionCookie(request);
+  const { pathname } = request.nextUrl;
+
+  // Don't redirect from sign-in/sign-up pages
+  if (["/sign-in", "/sign-up"].includes(pathname)) {
+    return NextResponse.next();
+  }
+
+  // Redirect unauthenticated users from protected routes
+  const protectedRoutes = ["/dashboard"]; // Add your protected routes here
+  const isProtectedRoute = protectedRoutes.some(route => pathname.startsWith(route));
+
+  if (isProtectedRoute && !sessionCookie) {
+    const returnTo = encodeURIComponent(pathname);
+    return NextResponse.redirect(new URL(`/sign-in?returnTo=${returnTo}`, request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/sign-in", "/sign-up"],
+};
+```
+
+### Step 5: Verify Installation
+
+1. Start your dev server: `npm run dev`
+2. Visit `http://localhost:3000/sign-up` to create an account
+3. Visit `http://localhost:3000/sign-in` to sign in
+4. Try accessing `/dashboard` - you should be redirected to sign-in if not authenticated
+
+---
+
+## Usage Examples
+
+### Using Auth Client in Components
+
+```typescript
+"use client";
+
+import { authClient } from "@/lib/auth-client";
+
+export default function ProfileButton() {
+  const handleSignOut = async () => {
+    await authClient.signOut({
+      fetchOptions: {
+        onSuccess: () => {
+          window.location.href = "/";
+        },
+      },
+    });
+  };
+
+  return <button onClick={handleSignOut}>Sign Out</button>;
+}
+```
+
+### Using Auth Server-Side
+
+```typescript
+import { auth } from "@/lib/auth";
+import { getSession } from "better-auth/next-js";
+
+export default async function DashboardPage() {
+  const session = await getSession({ auth });
+
+  if (!session) {
+    redirect("/sign-in");
+  }
+
+  return <div>Welcome, {session.user.email}!</div>;
+}
+```
+
+### Checking Authentication Status
+
+```typescript
+"use client";
+
+import { authClient } from "@/lib/auth-client";
+import { useEffect, useState } from "react";
+
+export default function AuthStatus() {
+  const [session, setSession] = useState(null);
+
+  useEffect(() => {
+    authClient.getSession().then(setSession);
+  }, []);
+
+  if (!session) {
+    return <div>Not signed in</div>;
+  }
+
+  return <div>Signed in as {session.user.email}</div>;
+}
+```
+
+---
+
+## Customization
+
+### Styling
+- Sign-in/sign-up pages use Tailwind CSS classes
+- Customize colors in `tailwind.config.ts`
+- Modify page layouts in `app/sign-in/page.tsx` and `app/sign-up/page.tsx`
+
+### Configuration
+- Auth configuration is in `lib/auth.ts`
+- Customize providers, session settings, and more
+- See [Better Auth documentation](https://www.better-auth.com/docs) for options
+
+### Protected Routes
+Edit `middleware.ts` to customize which routes require authentication:
+
+```typescript
+const protectedRoutes = [
+  "/dashboard",
+  "/settings",
+  "/admin"  // Add your custom routes
+];
+```
+
+---
+
+## Integration Points
+
+### Files That May Need Manual Updates
+
+**middleware.ts** (required):
+- Add route protection logic (see Step 4 above)
+
+**db/schema.ts** (if database module not installed):
+- Import or merge auth schema tables
+
+**lib/email.ts** (optional):
+- For password reset emails, you'll need email functionality
+- See Email module for integration
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue:** "Database connection failed" error
+**Solution:** 
+- Ensure `DATABASE_URL` is set in `.env.local`
+- Run database migrations: `npm run db:push`
+- Verify database is accessible
+
+**Issue:** Google OAuth not working
+**Solution:**
+- Verify `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are set
+- Check redirect URI matches in Google Cloud Console
+- Ensure `NEXT_PUBLIC_APP_URL` is correct
+
+**Issue:** "BETTER_AUTH_SECRET is required"
+**Solution:**
+- Generate a secret: `openssl rand -base64 32`
+- Add to `.env.local`: `BETTER_AUTH_SECRET="your-secret"`
+
+**Issue:** Users can't sign in after sign up
+**Solution:**
+- Check database migrations ran successfully
+- Verify `user` and `session` tables exist
+- Check database connection
+
+---
+
+## Next Steps
+
+After installing this module:
+
+1. Set up Google OAuth (optional but recommended)
+2. Configure email for password resets (requires Email module)
+3. Customize protected routes in middleware
+4. Add user profile pages
+5. Integrate with Payments module for subscription management
+
+---
+
+## Related Modules
+
+This module works well with:
+- **Database Module** - Required for user/session storage
+- **Email Module** - For password reset emails
+- **Payments Module** - For subscription-based access control
+
+---
+
+## Module Status
+
+✅ **Core Files Included** - All auth pages and utilities  
+⚠️ **Requires Database** - Database module must be installed first  
+✅ **UI Components** - Uses base package components  
+✅ **Well Documented** - Comprehensive integration guide
+

package/features/auth/app/api/auth/[...all]/route.ts

@@ -0,0 +1,4 @@
+import { auth } from "@/lib/auth"; // path to your auth file
+import { toNextJsHandler } from "better-auth/next-js";
+
+export const { POST, GET } = toNextJsHandler(auth);

package/features/auth/app/dashboard/layout.tsx

@@ -0,0 +1,15 @@
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Dashboard",
+  description: "Your application dashboard",
+};
+
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <>{children}</>;
+}
+

package/features/auth/app/dashboard/page.tsx

@@ -0,0 +1,140 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { authClient } from "@/lib/auth-client";
+import { useRouter } from "next/navigation";
+import { useEffect, useState } from "react";
+import { toast } from "sonner";
+
+export default function DashboardPage() {
+  const router = useRouter();
+  const [session, setSession] = useState<any>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    async function checkSession() {
+      try {
+        const currentSession = await authClient.getSession();
+        setSession(currentSession);
+      } catch (error) {
+        console.error("Failed to get session:", error);
+        router.push("/sign-in");
+      } finally {
+        setLoading(false);
+      }
+    }
+    checkSession();
+  }, [router]);
+
+  const handleSignOut = async () => {
+    try {
+      await authClient.signOut({
+        fetchOptions: {
+          onSuccess: () => {
+            toast.success("Signed out successfully");
+            router.push("/");
+          },
+        },
+      });
+    } catch (error) {
+      console.error("Sign out error:", error);
+      toast.error("Failed to sign out");
+    }
+  };
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center min-h-screen">
+        <div className="text-center">
+          <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-gray-900 dark:border-gray-100 mx-auto"></div>
+          <p className="mt-4 text-gray-600 dark:text-gray-400">Loading...</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (!session) {
+    return null; // Will redirect to sign-in
+  }
+
+  return (
+    <div className="min-h-screen bg-gray-50 dark:bg-gray-900 p-8">
+      <div className="max-w-4xl mx-auto">
+        <div className="flex justify-between items-center mb-8">
+          <div>
+            <h1 className="text-3xl font-bold text-gray-900 dark:text-white">
+              Dashboard
+            </h1>
+            <p className="text-gray-600 dark:text-gray-400 mt-2">
+              Welcome back, {session.user?.name || session.user?.email}!
+            </p>
+          </div>
+          <Button onClick={handleSignOut} variant="outline">
+            Sign Out
+          </Button>
+        </div>
+
+        <div className="grid gap-6 md:grid-cols-2">
+          <Card>
+            <CardHeader>
+              <CardTitle>Account Information</CardTitle>
+              <CardDescription>Your account details</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div className="space-y-2">
+                <div>
+                  <p className="text-sm text-gray-600 dark:text-gray-400">Email</p>
+                  <p className="font-medium">{session.user?.email}</p>
+                </div>
+                {session.user?.name && (
+                  <div>
+                    <p className="text-sm text-gray-600 dark:text-gray-400">Name</p>
+                    <p className="font-medium">{session.user.name}</p>
+                  </div>
+                )}
+                {session.user?.image && (
+                  <div>
+                    <p className="text-sm text-gray-600 dark:text-gray-400">Profile Image</p>
+                    <img
+                      src={session.user.image}
+                      alt="Profile"
+                      className="w-16 h-16 rounded-full mt-2"
+                    />
+                  </div>
+                )}
+              </div>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Getting Started</CardTitle>
+              <CardDescription>Next steps for your application</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div className="space-y-4">
+                <p className="text-sm text-gray-600 dark:text-gray-400">
+                  Your authentication is set up and working! Here are some things you can do next:
+                </p>
+                <ul className="list-disc list-inside space-y-2 text-sm text-gray-600 dark:text-gray-400">
+                  <li>Customize this dashboard page</li>
+                  <li>Add more protected routes</li>
+                  <li>Install additional modules (payments, etc.)</li>
+                  <li>Configure your database connection</li>
+                </ul>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      </div>
+    </div>
+  );
+}
+