# Roam Coffee

Roam Coffee is a subscription platform for independent roasters and curious coffee drinkers. Customers create a taste profile, choose a delivery schedule, and receive freshly roasted beans matched to their preferences.

## Features

- Personalized coffee recommendations based on roast, origin, and brew method
- Flexible weekly, biweekly, and monthly subscriptions
- Whole-bean or grind-specific fulfillment
- Subscription pause, skip, and cancellation controls
- Rotating catalog from independent roasters
- Stripe-powered checkout and recurring billing
- Customer delivery and order history
- Transactional email notifications
- Administrative tools for products, inventory, and shipments

## Installation

### Prerequisites

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

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

Run the test suite:

```bash
npm test
```

Run linting and type checks:

```bash
npm run lint
npm run typecheck
```

Create a production build:

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

To test Stripe webhooks locally, forward events 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`.

### Subscription flow

1. Create an account or sign in.
2. Complete the taste profile.
3. Select a bag size, grind, and delivery frequency.
4. Add a shipping address and payment method.
5. Confirm the subscription.
6. Manage upcoming deliveries from the account dashboard.

## Configuration

Configuration is loaded from environment variables in `.env`.

| Variable | Required | Description |
| --- | --- | --- |
| `DATABASE_URL` | Yes | PostgreSQL connection string |
| `APP_URL` | Yes | Public application URL |
| `SESSION_SECRET` | Yes | Secret used to sign sessions |
| `STRIPE_SECRET_KEY` | Yes | Stripe server-side API key |
| `STRIPE_PUBLISHABLE_KEY` | Yes | Stripe browser API key |
| `STRIPE_WEBHOOK_SECRET` | Yes | Stripe webhook signing secret |
| `EMAIL_FROM` | Yes | Sender address for transactional email |
| `RESEND_API_KEY` | Yes | Resend API key |
| `SUPPORT_EMAIL` | No | Customer support address |
| `DEFAULT_CURRENCY` | No | ISO currency code; defaults to `USD` |
| `LOG_LEVEL` | No | Logging level; defaults to `info` |

Example:

```dotenv
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/roam_coffee
APP_URL=http://localhost:3000
SESSION_SECRET=replace-with-a-long-random-value
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_PUBLISHABLE_KEY=pk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
EMAIL_FROM=Roam Coffee <orders@example.com>
RESEND_API_KEY=re_xxx
SUPPORT_EMAIL=support@example.com
DEFAULT_CURRENCY=USD
LOG_LEVEL=debug
```

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