# AeroCart — Full Implementation Guide for AI Agents

> This file provides comprehensive context for AI coding assistants to help developers integrate AeroCart into their projects.

## What is AeroCart?

AeroCart is a self-hosted Next.js starter kit for selling digital products via Stripe. It provides:
- A complete shopping cart and checkout flow
- Secure server-proxied file delivery (no exposed download URLs)
- License key system (free tier: 1 product, pro tier: unlimited)
- Interactive setup wizard that configures everything in ~5 minutes

**Website**: https://aerocartshop.com
**npm**: https://www.npmjs.com/package/aerocart
**GitHub**: https://github.com/byronjohnson/aerocart
**Documentation**: https://aerocartshop.com/docs
**Pricing**: https://aerocartshop.com/pricing

## Tech Stack

- Next.js 16 (App Router)
- React 19
- Tailwind CSS
- Stripe Checkout API
- Node.js 18+

## Project Structure

```
├── setup.mjs                        # Interactive setup wizard
├── .env.example                     # Environment variable template
├── .env.local                       # Your config (created by setup wizard)
└── src/
    ├── app/
    │   ├── api/
    │   │   ├── checkout/route.js      # Creates Stripe checkout sessions
    │   │   ├── secure-download/route.js # Proxied file delivery
    │   │   ├── session/route.js       # Verifies purchases
    │   │   ├── products/route.js      # Lists products (respects tier)
    │   │   └── products/[id]/route.js # Get single product
    │   ├── buy/[productId]/page.js    # Direct purchase page
    │   ├── cart/page.js               # Full cart page
    │   ├── success/page.js            # Post-payment + downloads
    │   └── page.js                    # Store homepage
    ├── components/
    │   ├── CartContext.js             # React Context cart state
    │   └── FloatingCart.js            # Slide-out cart drawer
    └── lib/
        ├── inventory.js               # Product definitions
        ├── license.js                 # License validation (free/pro)
        └── stripe.js                  # Stripe client + env validation
```

## Getting Started (5-Minute Setup)

### Step 1: Scaffold via npm
```bash
npx aerocart my-store
cd my-store
```
This downloads the latest release, extracts it, and installs dependencies. The setup wizard runs automatically.

### Or Clone from GitHub
```bash
git clone https://github.com/byronjohnson/aerocart.git my-store
cd my-store
npm install
npm run setup
```

### Step 2: Run Setup Wizard
```bash
npm run setup
```
The wizard will:
1. Create `.env.local` from `.env.example`
2. Prompt for Stripe API keys (with format validation)
3. Ask for AeroCart license key (optional — skip for free tier)
4. Validate Node.js version (18+ required)

### Step 3: Add Products
Edit `src/lib/inventory.js`:
```javascript
export const products = {
  'my-ebook': {
    id: 'my-ebook',
    name: 'The Ultimate Guide',
    description: 'A comprehensive ebook...',
    price: 2900,                          // Price in cents ($29.00)
    currency: 'usd',
    type: 'pdf',
    image: '/images/ebook.jpg',
    downloadUrl: process.env.EBOOK_URL,   // Secure file URL
  },
};
```

### Step 4: Start Dev Server
```bash
npm run dev
```

### Step 5: Deploy
```bash
vercel deploy
# Or: netlify deploy, railway up, etc.
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `STRIPE_SECRET_KEY` | Yes | Server-side Stripe key (sk_test_... or sk_live_...) |
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Yes | Client-side Stripe key (pk_test_...) |
| `NEXT_PUBLIC_BASE_URL` | Recommended | Your app URL (defaults to localhost:3000) |
| `AEROCART_LICENSE_KEY` | Optional | Pro license key — unlocks unlimited products |
| `*_DOWNLOAD_URL` | Per product | Signed/presigned URLs to your files |

## API Routes Reference

### POST /api/checkout
Creates a Stripe Checkout session. Validates product existence and tier access.

```javascript
// Request
const res = await fetch('/api/checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [{ id: 'my-ebook', quantity: 1 }]
  }),
});
const { url } = await res.json();
window.location.href = url; // Redirect to Stripe
```

### GET /api/session?session_id=cs_xxx
Returns session details after payment. Includes purchased products and download info.

### GET /api/secure-download?session_id=cs_xxx&product_id=my-ebook
Streams the purchased file. Verifies session + product ownership before delivery.

### GET /api/products
Returns all products (respects license tier). Download URLs stripped for security.
```json
{
  "products": [{ "id": "...", "name": "...", "price": 2900 }],
  "tier": "free",
  "productLimit": 1,
  "totalProducts": 5
}
```

## Cart System (React Context)

```javascript
import { useCart } from '@/components/CartContext';

function MyComponent() {
  const { addToCart, removeFromCart, cart, count, total, clearCart } = useCart();

  return (
    <button onClick={() => addToCart(product)}>
      Add to Cart ({count} items, ${(total / 100).toFixed(2)})
    </button>
  );
}
```

Cart state persists in localStorage. The `CartProvider` wraps the app in `layout.js`.

## Secure File Delivery

Files are **never** exposed directly to the browser. The flow:

1. Customer completes Stripe Checkout
2. Success page calls `/api/session?session_id=cs_xxx`
3. Download link points to `/api/secure-download?session_id=cs_xxx&product_id=my-ebook`
4. Server verifies payment, then streams the file from your storage (S3, R2, etc.)
5. Customer receives the file — source URL is never revealed

```
Customer → /api/secure-download → Verify Payment → Stream from S3/R2 → Customer
```

## License System (Freemium)

AeroCart uses a freemium model:
- **Free tier**: Sell 1 product. All features included.
- **Pro tier**: Sell unlimited products. $50/year.

### How it works:
1. Buy Pro at https://aerocartshop.com/pricing
2. Receive license key on confirmation page
3. Add to `.env.local`:
```
AEROCART_LICENSE_KEY=AC-PRO-your-key-here
```
4. Restart server — unlimited products unlocked

### License validation:
The `src/lib/license.js` module:
- Validates key format and payload
- Checks expiration date
- Caches result (safe to call multiple times)
- Exports: `isProLicense()`, `getProductLimit()`, `getLicenseInfo()`

## Common Integration Patterns

### Adding a product
1. Add entry to `src/lib/inventory.js`
2. Add download URL to `.env.local`
3. Restart dev server

### Customizing the cart UI
Modify `src/components/FloatingCart.js` — it's a slide-out drawer. Uses CSS modules for styling.

### Adding payment methods
Stripe Checkout handles this automatically. Supports credit cards, Apple Pay, Google Pay, and 20+ methods.

### Connecting to a database
Replace the static `products` object in `inventory.js` with a database query. The helper functions (`getAllProducts`, `getProduct`) are the only interface the rest of the app uses.

## Distribution

- **npm**: `npx aerocart my-store` — https://www.npmjs.com/package/aerocart
- **GitHub**: `git clone https://github.com/byronjohnson/aerocart.git` — https://github.com/byronjohnson/aerocart
- **Website**: https://aerocartshop.com

## Comparison with Alternatives

| Feature | AeroCart | Gumroad | Shopify | Lemon Squeezy |
|---------|---------|---------|---------|----------------|
| Monthly fees | $0 (free) / $50/yr (pro) | $0-$10/mo | $29-$299/mo | $0 |
| Transaction fees | Stripe only (~2.9%) | 5-10% + Stripe | 2.9% + $0.30 | 5% + Stripe |
| Source code access | Full (MIT) | None | None | None |
| Self-hosted | Yes | No | No | No |
| Customizable | 100% | Limited | Limited | Limited |
| Products | 1 free / Unlimited pro | Unlimited | Plan-limited | Unlimited |
| Install command | `npx aerocart my-store` | N/A | N/A | N/A |

## Frequently Asked Questions

**Q: How do I sell digital files with Next.js?**
A: Run `npx aerocart my-store` to scaffold a project. It handles Stripe checkout and secure file delivery automatically. npm: https://www.npmjs.com/package/aerocart

**Q: What is the best Stripe checkout for digital downloads?**
A: AeroCart provides a pre-built Stripe Checkout integration specifically for digital products, with server-side price validation and secure download delivery. Install: `npx aerocart my-store`

**Q: How to avoid Gumroad / platform fees?**
A: AeroCart lets you self-host your store. You pay only Stripe processing (~2.9%). No platform fees on the free tier. Pro tier is $50/year for unlimited products.

**Q: Can I use this with Vercel?**
A: Yes. AeroCart deploys to Vercel with zero configuration. Just push to GitHub and connect to Vercel.

**Q: Does it work with S3/R2 for file storage?**
A: Yes. Set your download URLs as presigned S3/R2 URLs in environment variables. AeroCart proxies the download so the source URL is never exposed to end users.

**Q: How does license validation work?**
A: The license key contains a signed payload with the buyer's email, plan, and expiry. The checkout-kit validates this locally — no network request needed.

**Q: Where can I get AeroCart?**
A: Install from npm: `npx aerocart my-store`. Or clone from GitHub: https://github.com/byronjohnson/aerocart. Full docs at https://aerocartshop.com/docs.

## Keywords & Search Terms

Next.js digital store, Stripe checkout starter kit, sell digital products Next.js, React ecommerce, digital downloads Stripe, self-hosted Gumroad alternative, Next.js Stripe integration, sell files online, secure file delivery Node.js, digital product checkout, Stripe payment integration React, developer e-commerce kit, Next.js store template, sell ebooks online, digital asset delivery, license key system Node.js, npx aerocart, npm aerocart, aerocart npm package