# Bookra Project Notes

## Build & Test Commands
- `npm run build:frontend` — Build SolidJS frontend
- `npm run build:backend` — Build Go backend
- `npm run test` — Run backend tests
- `npm run verify` — Full verification (client gen, lint, test, build)

## Database
- Uses PostgreSQL via Neon (pooled URL for app, direct URL for migrations)
- Migrations with Goose: `npm run db:migrate:up`
- SQLC for typed queries: `npm run db:generate`

## SMS Feature

### Architecture
- Optional add-on, off by default
- Only available on **Pro** and **Business** plans
- Uses SMS Manager.cz JSON API v2 (`https://api.smsmngr.com/v2`)
- Metered billing via Stripe (1.50 CZK per SMS)
- Tracks usage locally in `sms_usage_logs` table

### Database Tables
- `tenant_sms_settings` — per-tenant SMS config (enabled, sender, limit, stripe item ID)
- `sms_usage_logs` — every SMS sent with cost tracking
- `sms_monthly_reports` — aggregated monthly usage for invoices

### API Endpoints
- `GET /v1/sms/settings` — Get SMS settings + current month stats
- `POST /v1/sms/settings` — Enable/disable SMS, configure sender/limit
- `POST /v1/sms/send` — Send an SMS (tracked & billed)
- `GET /v1/sms/usage` — Usage for a specific month
- `GET /v1/sms/history` — Recent SMS logs
- `GET /v1/sms/invoices` — Monthly invoice reports
- `POST /v1/internal/jobs/sms/invoices` — Cron endpoint to generate monthly reports & emails

### What to Configure on Stripe
1. **Create standard Prices** for SMS in each currency:
   - Product: "SMS Messages"
   - Price: 1.50 CZK per unit (or equivalent in USD/EUR)
   - Billing mode: **Standard** one-time (not metered)
   - No free trial

2. **Environment variables** to add:
   ```
   BOOKRA_STRIPE_SMS_CZK_PRICE_ID=price_xxx
   BOOKRA_STRIPE_SMS_USD_PRICE_ID=price_yyy
   BOOKRA_STRIPE_SMS_EUR_PRICE_ID=price_zzz
   BOOKRA_SMSMANAGER_API_KEY=your_smsmanager_api_key
   ```

### Stripe CLI Commands (for testing)
```bash
# Login to Stripe
stripe login

# Create test product
stripe products create --name="SMS Messages"

# Create prices in each currency (replace prod_xxx with actual product ID)
stripe prices create --product=prod_xxx --unit-amount=150 --currency=czk
stripe prices create --product=prod_xxx --unit-amount=6 --currency=usd
stripe prices create --product=prod_xxx --unit-amount=6 --currency=eur

# Listen to webhooks locally
stripe listen --forward-to http://localhost:8080/v1/webhooks/stripe
```

### Monthly Invoice Flow
- At month end, a background job (`POST /v1/internal/jobs/sms/invoices`) aggregates all SMS usage per tenant
- It creates a Stripe `invoiceitem` with quantity = messages sent × 1.50 CZK (or configured currency price)
- The item is added to the customer's next subscription invoice automatically
- A usage summary email is sent showing: messages sent, total cost, and invoice details
- Reports are visible in-app under Settings > SMS Messages > Invoice reports

### Taxes
- The 1.50 CZK is the base unit price
- Stripe handles tax calculation based on the customer's location and your tax settings
- Displayed prices in the app show pre-tax amounts; the final invoice includes tax

### No Free Trial
- SMS is charged from the first message
- No trial period — usage is aggregated and invoiced monthly