AeroCart

1. Getting Started

Install dependencies and configure your Stripe keys.

npm install

Create a .env.local file:

# Required: Stripe API Keys

STRIPE_SECRET_KEY=sk_test_...

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

Get your keys from the Stripe Dashboard.

2. Project Structure

src/
├── app/
│   ├── api/
│   │   ├── checkout/route.js      # Creates Stripe sessions
│   │   ├── secure-download/route.js # Secure file delivery
│   │   └── session/route.js       # Fetch purchased products
│   ├── success/page.js            # Post-payment page
│   └── page.js                    # Homepage
├── components/
│   ├── CartContext.js             # Cart state management
│   └── FloatingCart.js            # Cart UI component
└── lib/
    ├── inventory.js               # ⭐ Product definitions
    └── stripe.js                  # Stripe singleton

3. Defining Products

All products are defined in src/lib/inventory.js. This is the only file you need to edit to add or modify products.

src/lib/inventory.js

export const products = {
  'my-ebook': {
    id: 'my-ebook',
    name: 'The Ultimate Guide',
    description: 'A comprehensive guide to...',
    price: 2900,           // $29.00 in cents
    currency: 'usd',
    type: 'pdf',           // Used for file extension
    image: '/images/ebook.jpg',
    downloadUrl: process.env.EBOOK_S3_URL,
  },
};

// Helper functions (already provided)
export function getAllProducts() { ... }
export function getProduct(id) { ... }
export function getDownloadUrl(id) { ... }

Tip: The downloadUrl can be a string or a function that returns a URL. Use environment variables for production URLs (e.g., signed S3 URLs).

4. Using the Cart

The cart is already set up in layout.js. Use the useCart hook anywhere in your app.

import { useCart } from '@/components/CartContext'; import { getAllProducts } from '@/lib/inventory'; export default function ProductCard() { const { addToCart, cart, count, total } = useCart(); const products = getAllProducts(); return ( <div> {products.map(product => ( <button key={product.id} onClick={() => addToCart(product)} > Add {product.name} to Cart </button> ))} <p>Items in cart: {count}</p> <p>Total: ${(total / 100).toFixed(2)}</p> </div> ); }

Available Cart Methods

Method	Description
addToCart(product)	Add item or increment quantity
removeFromCart(id)	Remove item completely
clearCart()	Empty entire cart
toggleCart()	Open/close cart drawer
count	Total number of items
total	Total price in cents

5. Secure Delivery

The secure download flow is handled automatically by /api/secure-download.

How it works:

User completes checkout → redirected to /success?session_id=xxx
Success page calls /api/session to get purchased product IDs
User clicks "Download" → hits /api/secure-download?session_id=xxx&product_id=yyy
API verifies Stripe session is paid
API checks product was in the purchase metadata
API fetches file from your private URL and streams to user

Important: Your source files (S3, R2, etc.) should be private. Only your server-side code should have access via secret URLs.

6. API Reference

POST /api/checkout

Creates a Stripe Checkout session.

// Request Body
{ "items": [{ "id": "product-id", "quantity": 1 }] }

// Response
{ "url": "https://checkout.stripe.com/..." }

GET /api/session

Returns purchased products for a session.

// Request
GET /api/session?session_id=cs_xxx

// Response
{ 
  "status": "paid",
  "products": [{ "id": "...", "name": "...", "type": "pdf" }]
}

GET /api/secure-download

Streams a purchased file to the user.

// Request
GET /api/secure-download?session_id=cs_xxx&product_id=my-ebook

// Response
Binary file stream with Content-Disposition: attachment

Integration Documentation