# Roam Coffee

Roam Coffee is a subscription platform for specialty coffee lovers. Customers can choose their roast preferences, delivery schedule, grind size, and bag quantity, then receive freshly roasted beans from independent roasters.

## Features

- Personalized coffee subscriptions
- Weekly, biweekly, and monthly deliveries
- Whole-bean and ground coffee options
- Flexible bag quantities and sizes
- Subscription pause, skip, and cancellation
- Secure checkout and recurring billing
- Customer order and delivery history
- Admin tools for managing coffees, roasters, and shipments
- Email notifications for renewals and deliveries

## Requirements

- Node.js 20 or later
- npm 10 or later
- PostgreSQL 15 or later
- A Stripe account for subscription billing
- An SMTP provider for transactional email

## Installation

Clone the repository and install dependencies:

```bash
git clone https://github.com/roam-coffee/subscriptions.git
cd subscriptions
npm install
```

Create a local environment file:

```bash
cp .env.example .env
```

Create the database and run migrations:

```bash
npm run db:create
npm run db:migrate
npm run db:seed
```

Start the development server:

```bash
npm run dev
```

The application will be available at `http://localhost:3000`.

## Usage

Create an account, complete the taste profile, and select a subscription plan. The seeded development database includes sample coffees and roasters for testing the recommendation and checkout flows.

Useful commands:

```bash
npm run dev          # Start the development server
npm run build        # Create a production build
npm start            # Run the production build
npm test             # Run the test suite
npm run lint         # Check code quality
npm run db:migrate   # Apply database migrations
npm run db:seed      # Load development sample data
```

To test billing locally, forward Stripe webhook events to the application:

```bash
stripe listen --forward-to localhost:3000/api/webhooks/stripe
```

Use Stripe test cards during checkout. No real charges are created in test mode.

## Configuration

The application is configured with environment variables in `.env`.

```dotenv
NODE_ENV=development
APP_URL=http://localhost:3000
PORT=3000

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/roam_coffee

SESSION_SECRET=replace-with-a-long-random-value

STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=username
SMTP_PASSWORD=password
EMAIL_FROM=Roam Coffee <orders@example.com>

DEFAULT_CURRENCY=USD
DEFAULT_DELIVERY_INTERVAL=monthly
```

### Required variables

| Variable | Description |
| --- | --- |
| `DATABASE_URL` | PostgreSQL connection string |
| `SESSION_SECRET` | Secret used to sign customer sessions |
| `STRIPE_SECRET_KEY` | Server-side Stripe API key |
| `STRIPE_PUBLISHABLE_KEY` | Browser-safe Stripe API key |
| `STRIPE_WEBHOOK_SECRET` | Signature secret for Stripe webhooks |
| `SMTP_HOST` | Transactional email server hostname |
| `SMTP_USER` | Transactional email username |
| `SMTP_PASSWORD` | Transactional email password |

Use separate credentials for development, staging, and production. Never commit `.env` files or live payment credentials to source control.