shipd 0.1.3 → 0.2.0

package/features/payments/feature.config.json

@@ -0,0 +1,31 @@
+{
+  "name": "payments",
+  "version": "1.0.0",
+  "description": "Polar.sh subscription management and payment processing",
+  "dependencies": {
+    "@polar-sh/sdk": "^0.42.1"
+  },
+  "devDependencies": {},
+  "envVars": [
+    "POLAR_ACCESS_TOKEN",
+    "POLAR_SUCCESS_URL",
+    "POLAR_WEBHOOK_SECRET",
+    "NEXT_PUBLIC_STARTER_TIER",
+    "NEXT_PUBLIC_STARTER_SLUG",
+    "NEXT_PUBLIC_APP_URL"
+  ],
+  "files": [
+    "app/dashboard/payment/**/*",
+    "app/success/**/*",
+    "app/api/subscription/**/*",
+    "lib/subscription.ts",
+    "lib/polar-products.ts",
+    "payments-schema.ts"
+  ],
+  "requires": [
+    "auth",
+    "database"
+  ],
+  "conflicts": []
+}
+

package/features/payments/lib/polar-products.ts

@@ -0,0 +1,49 @@
+import { Polar } from '@polar-sh/sdk';
+
+const polarClient = new Polar({
+  accessToken: process.env.POLAR_ACCESS_TOKEN!,
+});
+
+export interface ProductDetails {
+  id: string;
+  name: string;
+  description: string | null;
+  prices: Array<{
+    id: string;
+    amount: number;
+    currency: string;
+    recurring_interval: 'month' | 'year';
+  }>;
+}
+
+/**
+ * Fetch product details from Polar
+ */
+export async function getProductDetails(
+  productId: string
+): Promise<ProductDetails | null> {
+  try {
+    const product = await polarClient.products.get({
+      id: productId,
+    });
+
+    if (!product) {
+      return null;
+    }
+
+    return {
+      id: product.id,
+      name: product.name,
+      description: product.description || null,
+      prices: (product.prices || []).map((price) => ({
+        id: price.id,
+        amount: price.priceAmount || 0,
+        currency: price.priceCurrency || 'usd',
+        recurring_interval: (price.recurringInterval as 'month' | 'year') || 'month',
+      })),
+    };
+  } catch (error) {
+    console.error('Error fetching product from Polar:', error);
+    return null;
+  }
+}

package/features/payments/lib/subscription.ts

@@ -0,0 +1,148 @@
+import { auth } from "@/lib/auth";
+import { db } from "@/db/drizzle";
+import { subscription } from "@/db/schema";
+import { eq } from "drizzle-orm";
+import { headers } from "next/headers";
+
+export type SubscriptionDetails = {
+  id: string;
+  productId: string;
+  status: string;
+  amount: number;
+  currency: string;
+  recurringInterval: string;
+  currentPeriodStart: Date;
+  currentPeriodEnd: Date;
+  cancelAtPeriodEnd: boolean;
+  canceledAt: Date | null;
+  organizationId: string | null;
+};
+
+export type SubscriptionDetailsResult = {
+  hasSubscription: boolean;
+  subscription?: SubscriptionDetails;
+  error?: string;
+  errorType?: "CANCELED" | "EXPIRED" | "GENERAL";
+};
+
+export async function getSubscriptionDetails(): Promise<SubscriptionDetailsResult> {
+  try {
+    const session = await auth.api.getSession({
+      headers: await headers(),
+    });
+
+    if (!session?.user?.id) {
+      return { hasSubscription: false };
+    }
+
+    const userSubscriptions = await db
+      .select()
+      .from(subscription)
+      .where(eq(subscription.userId, session.user.id));
+
+    if (!userSubscriptions.length) {
+      return { hasSubscription: false };
+    }
+
+    // Get the most recent active subscription
+    const activeSubscription = userSubscriptions
+      .filter((sub) => sub.status === "active")
+      .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime())[0];
+
+    if (!activeSubscription) {
+      // Check for canceled or expired subscriptions
+      const latestSubscription = userSubscriptions
+        .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime())[0];
+
+      if (latestSubscription) {
+        const now = new Date();
+        const isExpired = new Date(latestSubscription.currentPeriodEnd) < now;
+        const isCanceled = latestSubscription.status === "canceled";
+
+        return {
+          hasSubscription: true,
+          subscription: {
+            id: latestSubscription.id,
+            productId: latestSubscription.productId,
+            status: latestSubscription.status,
+            amount: latestSubscription.amount,
+            currency: latestSubscription.currency,
+            recurringInterval: latestSubscription.recurringInterval,
+            currentPeriodStart: latestSubscription.currentPeriodStart,
+            currentPeriodEnd: latestSubscription.currentPeriodEnd,
+            cancelAtPeriodEnd: latestSubscription.cancelAtPeriodEnd,
+            canceledAt: latestSubscription.canceledAt,
+            organizationId: null,
+          },
+          error: isCanceled ? "Subscription has been canceled" : isExpired ? "Subscription has expired" : "Subscription is not active",
+          errorType: isCanceled ? "CANCELED" : isExpired ? "EXPIRED" : "GENERAL",
+        };
+      }
+
+      return { hasSubscription: false };
+    }
+
+    return {
+      hasSubscription: true,
+      subscription: {
+        id: activeSubscription.id,
+        productId: activeSubscription.productId,
+        status: activeSubscription.status,
+        amount: activeSubscription.amount,
+        currency: activeSubscription.currency,
+        recurringInterval: activeSubscription.recurringInterval,
+        currentPeriodStart: activeSubscription.currentPeriodStart,
+        currentPeriodEnd: activeSubscription.currentPeriodEnd,
+        cancelAtPeriodEnd: activeSubscription.cancelAtPeriodEnd,
+        canceledAt: activeSubscription.canceledAt,
+        organizationId: null,
+      },
+    };
+  } catch (error) {
+    console.error("Error fetching subscription details:", error);
+    return {
+      hasSubscription: false,
+      error: "Failed to load subscription details",
+      errorType: "GENERAL",
+    };
+  }
+}
+
+// Simple helper to check if user has an active subscription
+export async function isUserSubscribed(): Promise<boolean> {
+  const result = await getSubscriptionDetails();
+  return result.hasSubscription && result.subscription?.status === "active";
+}
+
+// Helper to check if user has access to a specific product/tier
+export async function hasAccessToProduct(productId: string): Promise<boolean> {
+  const result = await getSubscriptionDetails();
+  return (
+    result.hasSubscription &&
+    result.subscription?.status === "active" &&
+    result.subscription?.productId === productId
+  );
+}
+
+// Helper to get user's current subscription status
+export async function getUserSubscriptionStatus(): Promise<"active" | "canceled" | "expired" | "none"> {
+  const result = await getSubscriptionDetails();
+  
+  if (!result.hasSubscription) {
+    return "none";
+  }
+  
+  if (result.subscription?.status === "active") {
+    return "active";
+  }
+  
+  if (result.errorType === "CANCELED") {
+    return "canceled";
+  }
+  
+  if (result.errorType === "EXPIRED") {
+    return "expired";
+  }
+  
+  return "none";
+}

package/features/payments/payments-schema.ts

@@ -0,0 +1,30 @@
+import { pgTable, text, timestamp, boolean, integer } from "drizzle-orm/pg-core";
+
+// Subscription table for Polar webhook data
+// Note: userId references user.id from db/schema.ts (user table is added by auth module)
+export const subscription = pgTable("subscription", {
+  id: text("id").primaryKey(),
+  createdAt: timestamp("createdAt").notNull(),
+  modifiedAt: timestamp("modifiedAt"),
+  amount: integer("amount").notNull(),
+  currency: text("currency").notNull(),
+  recurringInterval: text("recurringInterval").notNull(),
+  status: text("status").notNull(),
+  currentPeriodStart: timestamp("currentPeriodStart").notNull(),
+  currentPeriodEnd: timestamp("currentPeriodEnd").notNull(),
+  cancelAtPeriodEnd: boolean("cancelAtPeriodEnd").notNull().default(false),
+  canceledAt: timestamp("canceledAt"),
+  startedAt: timestamp("startedAt").notNull(),
+  endsAt: timestamp("endsAt"),
+  endedAt: timestamp("endedAt"),
+  customerId: text("customerId").notNull(),
+  productId: text("productId").notNull(),
+  discountId: text("discountId"),
+  checkoutId: text("checkoutId").notNull(),
+  customerCancellationReason: text("customerCancellationReason"),
+  customerCancellationComment: text("customerCancellationComment"),
+  metadata: text("metadata"), // JSON string
+  customFieldData: text("customFieldData"), // JSON string
+  userId: text("userId"), // References user.id (user table from auth module)
+});
+

package/features/seo/README.md

@@ -0,0 +1,302 @@
+# SEO Module - Integration Guide
+
+## Overview
+
+The SEO module provides a complete SEO foundation for your Next.js application, including automated sitemap generation, robots.txt, blog structure, and structured data utilities.
+
+## What's Included
+
+### Files Added
+
+- `app/sitemap.ts` - Automated sitemap generation
+- `app/robots.txt` - Search engine crawler instructions
+- `app/blog/` - Complete blog structure with example posts
+- `lib/seo-utils.ts` - Helper functions for structured data and metadata
+
+### Features
+
+✅ **Automated Sitemap Generation**
+- Dynamically generates sitemap.xml
+- Includes all major routes (home, blog, pricing, docs, etc.)
+- Supports blog posts with proper priorities and change frequencies
+
+✅ **Robots.txt**
+- Allows all crawlers by default
+- Blocks sensitive routes (API, dashboard, auth pages)
+- Points to sitemap location
+
+✅ **Blog Structure**
+- Blog listing page (`/blog`)
+- Individual blog post pages (`/blog/[slug]`)
+- Markdown content support via react-markdown
+- SEO-optimized metadata for each post
+
+✅ **Structured Data Utilities**
+- JSON-LD generation for WebApplication
+- BlogPosting structured data
+- Organization schema
+- OpenGraph and Twitter Card helpers
+
+## Dependencies
+
+This module requires:
+- `react-markdown` (for blog content)
+- `remark-gfm` (for GitHub Flavored Markdown)
+
+These are automatically added to your `package.json` when you append this module.
+
+## Environment Variables
+
+Add to your `.env.local`:
+
+```env
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+```
+
+For production, set this to your actual domain:
+```env
+NEXT_PUBLIC_APP_URL=https://yourdomain.com
+```
+
+## Manual Integration Steps
+
+### 1. Verify Files Were Copied
+
+After appending, check that these files exist:
+- `app/sitemap.ts`
+- `app/robots.txt`
+- `app/blog/page.tsx`
+- `app/blog/[slug]/page.tsx`
+- `lib/seo-utils.ts`
+
+### 2. Update Sitemap with Your Routes
+
+Edit `app/sitemap.ts` to include all your application routes:
+
+```typescript
+// Add your custom routes
+{
+  url: `${baseUrl}/your-custom-page`,
+  lastModified: new Date(),
+  changeFrequency: 'monthly',
+  priority: 0.8,
+}
+```
+
+### 3. Update Blog Posts
+
+Edit `app/blog/page.tsx` and `app/blog/[slug]/page.tsx` to use your actual blog content. In production, you might:
+- Fetch from a CMS (Contentful, Sanity, etc.)
+- Read from markdown files
+- Query from a database
+
+### 4. Add Structured Data to Layout
+
+In your `app/layout.tsx`, add structured data:
+
+```typescript
+import { generateWebAppStructuredData } from '@/lib/seo-utils';
+
+export default function RootLayout({ children }) {
+  const jsonLd = generateWebAppStructuredData(
+    'Your App Name',
+    'Your app description',
+    'https://yourdomain.com'
+  );
+
+  return (
+    <html>
+      <head>
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+        />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### 5. Add Structured Data to Blog Posts
+
+In `app/blog/[slug]/page.tsx`, add blog post structured data:
+
+```typescript
+import { generateBlogPostStructuredData } from '@/lib/seo-utils';
+
+export default function BlogPost({ params }) {
+  const post = getPost(params.slug);
+  
+  const jsonLd = generateBlogPostStructuredData(
+    post.title,
+    post.description,
+    `https://yourdomain.com/blog/${post.slug}`,
+    post.date,
+    post.dateModified,
+    post.author,
+    post.image
+  );
+
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
+      {/* Blog post content */}
+    </>
+  );
+}
+```
+
+## Usage Examples
+
+### Generate OpenGraph Metadata
+
+```typescript
+import { generateOpenGraphMetadata } from '@/lib/seo-utils';
+
+export const metadata = {
+  ...generateOpenGraphMetadata(
+    'Page Title',
+    'Page description',
+    'https://yourdomain.com/page',
+    'https://yourdomain.com/og-image.png'
+  ),
+};
+```
+
+### Generate Twitter Card Metadata
+
+```typescript
+import { generateTwitterCardMetadata } from '@/lib/seo-utils';
+
+export const metadata = {
+  twitter: generateTwitterCardMetadata(
+    'Page Title',
+    'Page description',
+    'https://yourdomain.com/twitter-image.png',
+    'yourhandle'
+  ),
+};
+```
+
+## Testing
+
+1. **Test Sitemap**: Visit `http://localhost:3000/sitemap.xml`
+2. **Test Robots.txt**: Visit `http://localhost:3000/robots.txt`
+3. **Test Blog**: Visit `http://localhost:3000/blog`
+4. **Test Blog Post**: Visit `http://localhost:3000/blog/getting-started-with-saas`
+
+## Customization
+
+### Update Robots.txt Rules
+
+Edit `app/robots.txt` to customize crawler access:
+
+```
+# Disallow specific paths
+Disallow: /admin/
+Disallow: /private/
+```
+
+### Add More Routes to Sitemap
+
+Edit `app/sitemap.ts` and add your routes to the return array.
+
+### Customize Blog Structure
+
+The blog pages are fully customizable. Update:
+- `app/blog/page.tsx` - Blog listing page
+- `app/blog/[slug]/page.tsx` - Individual blog post page
+
+## Related Modules
+
+- **Marketing Landing Page** - Works great with SEO for discoverability
+- **Documentation Pages** - Can be included in sitemap
+
+## Module Status
+
+✅ **Ready to Use** - Works immediately after append  
+✅ **Template Variables** - Uses {{APP_URL}} in robots.txt  
+✅ **No Conflicts** - Safe to append to any project
+
+## Troubleshooting
+
+### Sitemap Not Generating
+
+- Ensure `NEXT_PUBLIC_APP_URL` is set in `.env.local`
+- Check that `app/sitemap.ts` exists
+- Verify Next.js version supports `MetadataRoute.Sitemap`
+
+### Blog Posts Not Showing
+
+- Check that blog posts array is populated in `app/blog/page.tsx`
+- Verify markdown content exists in `app/blog/[slug]/page.tsx`
+- Ensure `react-markdown` and `remark-gfm` are installed
+
+### Structured Data Not Validating
+
+- Use [Google's Rich Results Test](https://search.google.com/test/rich-results)
+- Verify JSON-LD syntax is correct
+- Check that required fields are present
+
+---
+
+## AI Integration Prompt
+
+**For AI Assistants:** Use this prompt to understand and integrate the SEO module into an existing Next.js application.
+
+```
+The SEO module has been appended to this Next.js project. Your task is to ensure it's properly integrated and functional.
+
+**Installed Packages:**
+- react-markdown@^10.1.0 - Markdown rendering for blog posts
+- remark-gfm@^4.0.1 - GitHub Flavored Markdown support
+
+**Files Added:**
+- app/sitemap.ts - Automated sitemap generation (Next.js MetadataRoute)
+- app/robots.txt - Search engine crawler instructions
+- app/blog/page.tsx - Blog listing page with example posts
+- app/blog/[slug]/page.tsx - Individual blog post page with markdown support
+- lib/seo-utils.ts - Structured data helpers (JSON-LD, OpenGraph, Twitter Cards)
+
+**Environment Variables Required:**
+- NEXT_PUBLIC_APP_URL - Application URL (e.g., http://localhost:3000 or https://yourdomain.com)
+
+**Integration Steps:**
+1. Verify app/sitemap.ts exists and exports default sitemap() function
+2. Check that app/robots.txt exists (Next.js serves this automatically)
+3. Verify blog structure exists: app/blog/page.tsx and app/blog/[slug]/page.tsx
+4. Check that lib/seo-utils.ts exists with structured data helper functions
+5. Ensure NEXT_PUBLIC_APP_URL is set in .env.local
+6. Test sitemap: Visit /sitemap.xml (should return XML)
+7. Test robots.txt: Visit /robots.txt (should return text)
+8. Test blog: Visit /blog (should show blog listing)
+
+**Key Integration Points:**
+- Sitemap generation: app/sitemap.ts uses Next.js MetadataRoute.Sitemap API
+- Robots.txt: Next.js automatically serves app/robots.txt at /robots.txt
+- Blog structure: Example blog posts are hardcoded; replace with CMS/database in production
+- Structured data: Use lib/seo-utils.ts functions to generate JSON-LD for pages
+- Template variables: robots.txt uses {{APP_URL}} which gets replaced during init
+
+**Dependencies:**
+- No dependencies on other Shipd modules
+- Can be installed standalone
+
+**Common Issues to Check:**
+- If sitemap not generating: Check NEXT_PUBLIC_APP_URL is set, verify app/sitemap.ts exists
+- If blog posts not showing: Check blog posts array in app/blog/page.tsx is populated
+- If markdown not rendering: Ensure react-markdown and remark-gfm are installed
+- If structured data invalid: Use Google Rich Results Test to validate JSON-LD
+
+**Next Steps After Integration:**
+- Update sitemap.ts with all your application routes
+- Customize blog posts in app/blog/page.tsx and app/blog/[slug]/page.tsx
+- Add structured data to app/layout.tsx using generateWebAppStructuredData()
+- Add structured data to blog posts using generateBlogPostStructuredData()
+- Update robots.txt rules if needed (currently allows all, blocks /api/, /dashboard/)
+- Replace hardcoded blog posts with CMS/database queries in production
+```