Bookra/AGENTS.md

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)

# 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