feat(sms): implement SMS messaging and metered billing
CI / Frontend (push) Successful in 9m50s
CI / Go - apps/auth-service (push) Failing after 4s
CI / Go - apps/backend (push) Successful in 10m18s
CI / Docker publish - auth-service (push) Has been skipped
CI / Docker publish - backend (push) Has been skipped

Implement a complete SMS messaging system including:
- Integration with SMS Manager.cz API for sending messages.
- Metered billing via Stripe using monthly aggregate invoice items.
- Backend services for managing SMS settings, usage logging, and monthly reporting.
- Database migrations for tenant settings, usage logs, and monthly reports.
- Frontend dashboard components for SMS configuration, usage tracking, and history.
- Support for customer phone numbers in the booking flow.

Includes new migrations, backend services, and frontend UI components.
This commit is contained in:
Tomas Dvorak
2026-05-10 11:40:53 +02:00
parent 164a37e997
commit 7d3e3448cf
28 changed files with 3633 additions and 3190 deletions
+83
View File
@@ -0,0 +1,83 @@
# 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