# Ember Coffee

Ember Coffee is a subscription platform for freshly roasted, small-batch coffee delivered on a flexible schedule. Customers can choose their preferred roast, grind, quantity, and delivery frequency, then pause or adjust upcoming shipments from their account.

## Features

- Personalized coffee subscriptions
- Whole-bean and ground options
- Weekly, biweekly, and monthly deliveries
- Multiple roast profiles and bag sizes
- Subscription pause, skip, and cancellation
- Secure checkout and recurring billing
- Customer shipment and billing history
- Email notifications for upcoming orders
- Administrative tools for products, inventory, and subscriptions

## Requirements

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

## Installation

Clone the repository and install dependencies:

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

Create a local environment file:

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

Update `.env` with your database, Stripe, and email credentials. Then initialize the database:

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

### Development

Run the application with automatic reload:

```bash
npm run dev
```

Run the test suite:

```bash
npm test
```

Check formatting and linting:

```bash
npm run lint
npm run format:check
```

Create a production build:

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

### Stripe webhooks

Recurring billing events are processed through Stripe webhooks. For local development, forward events with the Stripe CLI:

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

Copy the webhook signing secret from the command output into `STRIPE_WEBHOOK_SECRET`.

### Seed account

The development seed creates an administrative user:

```text
Email: admin@ember.local
Password: coffee123
```

Change or remove these credentials before deploying outside a local environment.

## Configuration

Configuration is loaded from environment variables.

| Variable | Required | Description | Example |
| --- | --- | --- | --- |
| `NODE_ENV` | No | Application environment | `development` |
| `PORT` | No | HTTP server port | `3000` |
| `APP_URL` | Yes | Public application URL | `http://localhost:3000` |
| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgresql://postgres:postgres@localhost:5432/ember` |
| `SESSION_SECRET` | Yes | Secret used to sign sessions | `replace-with-a-long-random-value` |
| `STRIPE_SECRET_KEY` | Yes | Stripe server API key | `sk_test_...` |
| `STRIPE_PUBLISHABLE_KEY` | Yes | Stripe browser API key | `pk_test_...` |
| `STRIPE_WEBHOOK_SECRET` | Yes | Stripe webhook signing secret | `whsec_...` |
| `SMTP_HOST` | Yes | SMTP server hostname | `smtp.example.com` |
| `SMTP_PORT` | Yes | SMTP server port | `587` |
| `SMTP_USER` | Yes | SMTP username | `apikey` |
| `SMTP_PASSWORD` | Yes | SMTP password | `secret` |
| `EMAIL_FROM` | Yes | Sender address for customer emails | `Ember Coffee <hello@example.com>` |
| `ORDER_CUTOFF_DAYS` | No | Days before shipment when changes are locked | `2` |

Generate a suitable session secret with:

```bash
openssl rand -base64 32
```

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