# Roam Coffee

Roam Coffee is a subscription platform for discovering freshly roasted coffee from independent roasters. Customers choose their preferred roast, grind, quantity, and delivery schedule, then receive a rotating selection matched to their taste.

## Features

- Flexible weekly, biweekly, and monthly subscriptions
- Whole-bean and custom grind options
- Personalized roast and flavor preferences
- Rotating coffees from independent roasters
- Subscription pause, skip, and cancellation
- Stripe-powered checkout and billing
- Customer delivery and order history
- Transactional email notifications

## Requirements

- Node.js 20 or newer
- PostgreSQL 15 or newer
- npm 10 or newer
- Stripe account and API keys

## Installation

Clone the repository and install dependencies:

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

Create a local environment file:

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

Create the database and run migrations:

```bash
createdb roam_coffee
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

Run the development server:

```bash
npm run dev
```

Create an optimized production build:

```bash
npm run build
npm start
```

Run the test suite:

```bash
npm test
```

Other useful commands:

```bash
npm run lint
npm run typecheck
npm run db:migrate
npm run db:seed
```

To test subscription events locally, forward Stripe webhooks to the application:

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

Copy the webhook signing secret printed by the Stripe CLI into `STRIPE_WEBHOOK_SECRET`.

## Configuration

Configuration is loaded from environment variables.

| Variable | Required | Description |
| --- | --- | --- |
| `DATABASE_URL` | Yes | PostgreSQL connection string |
| `APP_URL` | Yes | Public application URL |
| `SESSION_SECRET` | Yes | Secret used to sign customer sessions |
| `STRIPE_SECRET_KEY` | Yes | Stripe server-side API key |
| `STRIPE_WEBHOOK_SECRET` | Yes | Stripe webhook signing secret |
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Yes | Stripe browser publishable key |
| `EMAIL_FROM` | Yes | Sender address for transactional email |
| `SMTP_HOST` | Yes | SMTP server hostname |
| `SMTP_PORT` | Yes | SMTP server port |
| `SMTP_USER` | Yes | SMTP username |
| `SMTP_PASSWORD` | Yes | SMTP password |
| `LOG_LEVEL` | No | Logging level; defaults to `info` |

Example development configuration:

```dotenv
DATABASE_URL=postgresql://localhost:5432/roam_coffee
APP_URL=http://localhost:3000
SESSION_SECRET=replace-with-a-long-random-value

STRIPE_SECRET_KEY=sk_test_example
STRIPE_WEBHOOK_SECRET=whsec_example
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_example

EMAIL_FROM=Roam Coffee <hello@example.com>
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USER=
SMTP_PASSWORD=

LOG_LEVEL=debug
```

Never commit `.env` files or production credentials to source control.