mirror of
https://github.com/Dvorinka/Bookra.git
synced 2026-06-03 20:13:00 +00:00
feat(sms): implement SMS messaging and metered billing
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:
@@ -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
|
||||
Reference in New Issue
Block a user