mirror of
https://github.com/Dvorinka/Bookra.git
synced 2026-06-03 20:13:00 +00:00
Tomas Dvorak
7d3e3448cf
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.
84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
# 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
|