rainbow/sentinela-go
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: tiered API plans (Free/Bronze/Gold/Platinum)

Browse Source 
- Free: $0, 30 req/min, market data only
- Bronze: $29/mo, 100 req/min, + companies & search
- Gold: $99/mo, 500 req/min, + filings & historical
- Platinum: $299/mo, 2000 req/min, all features + priority
- Plan-aware rate limiting per API key (or per IP for free)
- Usage tracking with daily aggregation
- GET /api/v1/plans — plan listing
- POST /api/v1/plans/register — instant free API key
- GET /api/v1/plans/usage — usage stats
- /pricing — dark-themed HTML pricing page
- X-RateLimit-* and X-Plan headers on every response
- Restricted endpoints return upgrade prompt
- Updated OpenAPI spec with security scheme
- 53 handlers, compiles clean
This commit is contained in:
Rainbow
2026-02-10 12:55:45 -03:00
parent 3080a60711
commit a2b0db8f3f
11 changed files with 807 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
internal/api/docs/openapi.yaml
View File

@@ -1,8 +1,17 @@
openapi: "3.0.3"
info:
title: Sentinela API
description: Brazilian Financial Data API — Real-time market data from BCB and CVM
version: 0.2.0
description: |
Brazilian Financial Data API — Real-time market data from BCB and CVM.
## API Plans
- **Free** ($0): 30 req/min, market data only, no API key needed
- **Bronze** ($29/mo): 100 req/min, + companies & search
- **Gold** ($99/mo): 500 req/min, all data including filings & bulk export
- **Platinum** ($299/mo): 2000 req/min, all data + webhooks, priority support, CSV export
Include your API key via `X-API-Key` header or `Authorization: Bearer <key>`.
version: 0.3.0
contact:
name: Sentinela
url: https://git.ophion.com.br/rainbow/sentinela-go
@@ -14,6 +23,8 @@ servers:
description: Current server
tags:
- name: Plans
description: API plan management, registration, and usage
- name: Health
description: Health check
- name: Companies
@@ -534,6 +545,108 @@ paths:
"429":
$ref: "#/components/responses/RateLimited"
/api/v1/plans:
get:
tags: [Plans]
summary: List available plans
description: Returns all available API plans with pricing and features
responses:
"200":
description: List of plans
content:
application/json:
schema:
type: object
properties:
plans:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
price:
type: number
currency:
type: string
rate_limit:
type: integer
features:
type: array
items:
type: string
restrictions:
type: array
items:
type: string
/api/v1/plans/usage:
get:
tags: [Plans]
summary: Get usage stats
description: Returns usage statistics for the authenticated API key
security:
- ApiKeyAuth: []
parameters:
- name: from
in: query
schema:
type: string
format: date
description: Start date (YYYY-MM-DD)
- name: to
in: query
schema:
type: string
format: date
description: End date (YYYY-MM-DD)
responses:
"200":
description: Usage statistics
"401":
description: API key required
/api/v1/plans/register:
post:
tags: [Plans]
summary: Register for free tier
description: Create a new API key on the free plan
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name, email]
properties:
name:
type: string
example: "John Doe"
email:
type: string
format: email
example: "john@example.com"
responses:
"201":
description: API key created
content:
application/json:
schema:
type: object
properties:
message:
type: string
api_key:
type: string
plan:
type: string
rate_limit:
type: integer
"400":
$ref: "#/components/responses/BadRequest"
/api/v1/search:
get:
tags: [Search]
@@ -569,6 +682,13 @@ paths:
$ref: "#/components/responses/RateLimited"
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key for authenticated access. Free tier works without a key.
parameters:
from:
name: from

100
internal/api/handlers/plans.go Normal file
View File

@@ -0,0 +1,100 @@
package handlers
import (
"strings"
"time"
"github.com/gofiber/fiber/v2"
)
func (h *Handler) ListPlans(c *fiber.Ctx) error {
plans := []fiber.Map{
{
"id": "free", "name": "Free", "price": 0, "currency": "USD",
"rate_limit": 30, "rate_limit_unit": "requests/minute",
"features": []string{"Market data (Selic, CDI, IPCA, FX)", "Market overview endpoint", "No API key needed"},
"restrictions": []string{"No company data", "No filing data", "No search"},
},
{
"id": "bronze", "name": "Bronze", "price": 29, "currency": "USD", "billing": "monthly",
"rate_limit": 100, "rate_limit_unit": "requests/minute",
"features": []string{"All market data", "Company data & search", "Full-text search", "API key authentication"},
"restrictions": []string{"No filing data", "No bulk export"},
},
{
"id": "gold", "name": "Gold", "price": 99, "currency": "USD", "billing": "monthly",
"rate_limit": 500, "rate_limit_unit": "requests/minute",
"features": []string{"All market data", "Company data & search", "Filing data", "Full search", "Historical data", "Bulk export"},
"restrictions": []string{"No webhooks", "No priority support"},
},
{
"id": "platinum", "name": "Platinum", "price": 299, "currency": "USD", "billing": "monthly",
"rate_limit": 2000, "rate_limit_unit": "requests/minute",
"features": []string{"All data access", "Webhooks", "Priority support", "Custom date ranges", "Raw CSV export", "2000 req/min"},
"restrictions": []string{},
},
}
return c.JSON(fiber.Map{"plans": plans})
}
func (h *Handler) PlanUsage(c *fiber.Ctx) error {
apiKey := c.Get("X-API-Key")
if apiKey == "" {
auth := c.Get("Authorization")
if strings.HasPrefix(auth, "Bearer ") {
apiKey = strings.TrimPrefix(auth, "Bearer ")
}
}
if apiKey == "" {
return c.Status(401).JSON(fiber.Map{"error": "API key required to view usage"})
}
ak, err := h.db.GetAPIKey(apiKey)
if err != nil {
return c.Status(401).JSON(fiber.Map{"error": "invalid API key"})
}
now := time.Now()
from := c.Query("from", now.AddDate(0, 0, -30).Format("2006-01-02"))
to := c.Query("to", now.Format("2006-01-02"))
stats, err := h.db.GetUsageStats(ak.ID, from, to)
if err != nil {
return c.Status(500).JSON(fiber.Map{"error": err.Error()})
}
return c.JSON(fiber.Map{
"plan": ak.Plan,
"rate_limit": ak.RateLimit,
"requests_today": ak.RequestsToday,
"requests_month": ak.RequestsMonth,
"usage": stats,
"period": fiber.Map{"from": from, "to": to},
})
}
func (h *Handler) RegisterPlan(c *fiber.Ctx) error {
var body struct {
Name string `json:"name"`
Email string `json:"email"`
}
if err := c.BodyParser(&body); err != nil {
return c.Status(400).JSON(fiber.Map{"error": "invalid request body"})
}
if body.Name == "" || body.Email == "" {
return c.Status(400).JSON(fiber.Map{"error": "name and email are required"})
}
ak, err := h.db.CreateAPIKey(body.Name, body.Email, "free")
if err != nil {
return c.Status(500).JSON(fiber.Map{"error": "failed to create API key"})
}
return c.Status(201).JSON(fiber.Map{
"message": "API key created successfully",
"api_key": ak.Key,
"plan": ak.Plan,
"rate_limit": ak.RateLimit,
"note": "Store your API key securely. Include it in requests as X-API-Key header.",
})
}

152
internal/api/handlers/pricing.go Normal file
View File

@@ -0,0 +1,152 @@
package handlers
import "github.com/gofiber/fiber/v2"
func (h *Handler) PricingPage(c *fiber.Ctx) error {
c.Set("Content-Type", "text/html")
return c.SendString(pricingHTML)
}
const pricingHTML = `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Sentinela API - Pricing</title>
<style>
*{margin:0;padding:0;box-sizing:border-box}
body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#0a0e17;color:#e1e5ee;min-height:100vh}
.container{max-width:1200px;margin:0 auto;padding:40px 20px}
h1{text-align:center;font-size:2.5rem;margin-bottom:8px;background:linear-gradient(135deg,#00d4aa,#7c3aed);-webkit-background-clip:text;-webkit-text-fill-color:transparent}
.subtitle{text-align:center;color:#8892a4;font-size:1.1rem;margin-bottom:48px}
.plans{display:grid;grid-template-columns:repeat(auto-fit,minmax(260px,1fr));gap:24px;margin-bottom:64px}
.plan{background:#131a2b;border:1px solid #1e293b;border-radius:16px;padding:32px 24px;position:relative;transition:transform .2s,border-color .2s}
.plan:hover{transform:translateY(-4px);border-color:#7c3aed}
.plan.featured{border-color:#00d4aa;background:linear-gradient(180deg,#0f1a2e 0%,#131a2b 100%)}
.plan.featured::before{content:"MOST POPULAR";position:absolute;top:-12px;left:50%;transform:translateX(-50%);background:linear-gradient(135deg,#00d4aa,#059669);color:#fff;font-size:.7rem;font-weight:700;padding:4px 16px;border-radius:20px;letter-spacing:1px}
.plan-name{font-size:1.3rem;font-weight:700;margin-bottom:4px}
.plan-price{font-size:2.8rem;font-weight:800;margin:16px 0 4px}
.plan-price span{font-size:.9rem;font-weight:400;color:#8892a4}
.plan-billing{color:#8892a4;font-size:.85rem;margin-bottom:24px}
.plan-rate{background:#1e293b;border-radius:8px;padding:8px 12px;margin-bottom:20px;font-size:.9rem;color:#00d4aa;text-align:center}
.features{list-style:none;margin-bottom:28px}
.features li{padding:6px 0;font-size:.9rem;color:#c1c9d6}
.features li::before{content:"✓ ";color:#00d4aa;font-weight:700}
.features li.no::before{content:"✗ ";color:#4a5568}
.features li.no{color:#4a5568}
.btn{display:block;width:100%;padding:12px;border:none;border-radius:10px;font-size:1rem;font-weight:600;cursor:pointer;text-align:center;text-decoration:none;transition:opacity .2s}
.btn-free{background:#1e293b;color:#e1e5ee}
.btn-primary{background:linear-gradient(135deg,#00d4aa,#059669);color:#fff}
.btn-gold{background:linear-gradient(135deg,#f59e0b,#d97706);color:#fff}
.btn-plat{background:linear-gradient(135deg,#7c3aed,#6d28d9);color:#fff}
.btn:hover{opacity:.85}
table{width:100%;border-collapse:collapse;margin-top:16px}
th,td{padding:12px 16px;text-align:center;border-bottom:1px solid #1e293b;font-size:.9rem}
th{color:#8892a4;font-weight:600}
th:first-child,td:first-child{text-align:left}
td.yes{color:#00d4aa}
td.no{color:#4a5568}
.matrix-section{margin-top:64px}
.matrix-section h2{text-align:center;font-size:1.8rem;margin-bottom:8px}
.matrix-sub{text-align:center;color:#8892a4;margin-bottom:24px}
footer{text-align:center;color:#4a5568;font-size:.85rem;margin-top:64px;padding-bottom:32px}
footer a{color:#00d4aa;text-decoration:none}
</style>
</head>
<body>
<div class="container">
<h1>Sentinela API Plans</h1>
<p class="subtitle">Brazilian financial data API — real-time rates, companies, and filings</p>
<div class="plans">
<div class="plan">
<div class="plan-name">Free</div>
<div class="plan-price">$0<span></span></div>
<div class="plan-billing">Free forever</div>
<div class="plan-rate">30 requests/minute</div>
<ul class="features">
<li>Selic, CDI, IPCA rates</li>
<li>FX rates (USD/BRL)</li>
<li>Market overview</li>
<li class="no">Company data</li>
<li class="no">Filing data</li>
<li class="no">Search</li>
</ul>
<a href="/api/v1/plans/register" class="btn btn-free">Get Started</a>
</div>
<div class="plan">
<div class="plan-name">Bronze</div>
<div class="plan-price">$29<span>/mo</span></div>
<div class="plan-billing">Billed monthly</div>
<div class="plan-rate">100 requests/minute</div>
<ul class="features">
<li>All market data</li>
<li>Company data</li>
<li>Company search (FTS)</li>
<li>API key auth</li>
<li class="no">Filing data</li>
<li class="no">Bulk export</li>
</ul>
<a href="mailto:api@sentinela.dev?subject=Bronze Plan" class="btn btn-primary">Contact Us</a>
</div>
<div class="plan featured">
<div class="plan-name">Gold</div>
<div class="plan-price">$99<span>/mo</span></div>
<div class="plan-billing">Billed monthly</div>
<div class="plan-rate">500 requests/minute</div>
<ul class="features">
<li>All market data</li>
<li>Company data & search</li>
<li>Filing data</li>
<li>Historical data</li>
<li>Bulk export</li>
<li class="no">Webhooks</li>
</ul>
<a href="mailto:api@sentinela.dev?subject=Gold Plan" class="btn btn-gold">Contact Us</a>
</div>
<div class="plan">
<div class="plan-name">Platinum</div>
<div class="plan-price">$299<span>/mo</span></div>
<div class="plan-billing">Billed monthly</div>
<div class="plan-rate">2,000 requests/minute</div>
<ul class="features">
<li>Everything in Gold</li>
<li>Webhooks</li>
<li>Priority support</li>
<li>Custom date ranges</li>
<li>Raw CSV export</li>
<li>Dedicated capacity</li>
</ul>
<a href="mailto:api@sentinela.dev?subject=Platinum Plan" class="btn btn-plat">Contact Us</a>
</div>
</div>
<div class="matrix-section">
<h2>Feature Comparison</h2>
<p class="matrix-sub">Detailed breakdown of what's included in each plan</p>
<table>
<tr><th>Feature</th><th>Free</th><th>Bronze</th><th>Gold</th><th>Platinum</th></tr>
<tr><td>Selic / CDI / IPCA</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td></tr>
<tr><td>FX Rates</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td></tr>
<tr><td>Market Overview</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td></tr>
<tr><td>Company Data</td><td class="no">✗</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td></tr>
<tr><td>Company Search</td><td class="no">✗</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td></tr>
<tr><td>Filing Data</td><td class="no">✗</td><td class="no">✗</td><td class="yes">✓</td><td class="yes">✓</td></tr>
<tr><td>Historical Data</td><td class="no">✗</td><td class="no">✗</td><td class="yes">✓</td><td class="yes">✓</td></tr>
<tr><td>Bulk Export</td><td class="no">✗</td><td class="no">✗</td><td class="yes">✓</td><td class="yes">✓</td></tr>
<tr><td>Webhooks</td><td class="no">✗</td><td class="no">✗</td><td class="no">✗</td><td class="yes">✓</td></tr>
<tr><td>CSV Export</td><td class="no">✗</td><td class="no">✗</td><td class="no">✗</td><td class="yes">✓</td></tr>
<tr><td>Priority Support</td><td class="no">✗</td><td class="no">✗</td><td class="no">✗</td><td class="yes">✓</td></tr>
<tr><td>Rate Limit</td><td>30/min</td><td>100/min</td><td>500/min</td><td>2,000/min</td></tr>
</table>
</div>
<footer>
<p>Sentinela API — <a href="/docs">API Documentation</a> · <a href="/api/v1/plans">Plans API</a></p>
</footer>
</div>
</body>
</html>`

184
internal/api/middleware/plans.go Normal file
View File

@@ -0,0 +1,184 @@
package middleware
import (
"fmt"
"strings"
"sync"
"time"
"github.com/gofiber/fiber/v2"
"github.com/sentinela-go/internal/db"
)
type PlanConfig struct {
Name string
RateLimit int
Endpoints []string
Features []string
}
var Plans = map[string]PlanConfig{
"free": {Name: "Free", RateLimit: 30, Endpoints: []string{"/health", "/api/v1/market", "/api/v1/plans", "/docs", "/pricing"}, Features: []string{"market_data"}},
"bronze": {Name: "Bronze", RateLimit: 100, Endpoints: []string{"/health", "/api/v1/market", "/api/v1/companies", "/api/v1/search", "/api/v1/plans", "/docs", "/pricing"}, Features: []string{"market_data", "companies", "search"}},
"gold": {Name: "Gold", RateLimit: 500, Endpoints: []string{"/api/v1", "/health", "/docs", "/pricing"}, Features: []string{"market_data", "companies", "search", "filings", "historical", "bulk"}},
"platinum": {Name: "Platinum", RateLimit: 2000, Endpoints: []string{"/api/v1", "/health", "/docs", "/pricing"}, Features: []string{"market_data", "companies", "search", "filings", "historical", "bulk", "webhooks", "csv_export", "priority"}},
}
type tokenBucket struct {
tokens float64
lastCheck time.Time
}
type PlanMiddleware struct {
database *db.DB
mu sync.Mutex
buckets map[string]*tokenBucket
}
func NewPlanMiddleware(database *db.DB) fiber.Handler {
pm := &PlanMiddleware{
database: database,
buckets: make(map[string]*tokenBucket),
}
// Cleanup old buckets every 5 minutes
go func() {
for {
time.Sleep(5 * time.Minute)
pm.mu.Lock()
now := time.Now()
for k, b := range pm.buckets {
if now.Sub(b.lastCheck) > 10*time.Minute {
delete(pm.buckets, k)
}
}
pm.mu.Unlock()
}
}()
return pm.handle
}
func (pm *PlanMiddleware) handle(c *fiber.Ctx) error {
path := c.Path()
// Always allow these without any checks
if path == "/health" || path == "/docs" || path == "/docs/openapi.yaml" || path == "/pricing" {
c.Set("X-Plan", "free")
return c.Next()
}
// Plans endpoints are always accessible
if strings.HasPrefix(path, "/api/v1/plans") {
c.Set("X-Plan", "free")
return c.Next()
}
apiKey := c.Get("X-API-Key")
if apiKey == "" {
auth := c.Get("Authorization")
if strings.HasPrefix(auth, "Bearer ") {
apiKey = strings.TrimPrefix(auth, "Bearer ")
}
}
plan := "free"
rateLimit := 30
var keyRecord *db.APIKey
bucketKey := c.IP() // default: rate limit by IP
if apiKey != "" {
ak, err := pm.database.GetAPIKey(apiKey)
if err != nil {
return c.Status(401).JSON(fiber.Map{
"error": "invalid API key",
"message": "The provided API key is not valid or has been deactivated.",
})
}
keyRecord = ak
plan = ak.Plan
rateLimit = ak.RateLimit
bucketKey = fmt.Sprintf("key:%s", ak.Key)
}
// Check endpoint access
planCfg, ok := Plans[plan]
if !ok {
planCfg = Plans["free"]
}
if !isEndpointAllowed(path, planCfg.Endpoints) {
return c.Status(403).JSON(fiber.Map{
"error": "plan_restricted",
"message": fmt.Sprintf("Your %s plan does not include access to this endpoint.", planCfg.Name),
"current_plan": plan,
"upgrade_url": "/pricing",
})
}
// Rate limiting
pm.mu.Lock()
b, ok := pm.buckets[bucketKey]
if !ok {
b = &tokenBucket{tokens: float64(rateLimit), lastCheck: time.Now()}
pm.buckets[bucketKey] = b
}
now := time.Now()
elapsed := now.Sub(b.lastCheck).Seconds()
rate := float64(rateLimit) / 60.0
b.tokens += elapsed * rate
if b.tokens > float64(rateLimit) {
b.tokens = float64(rateLimit)
}
b.lastCheck = now
remaining := int(b.tokens)
if b.tokens < 1 {
pm.mu.Unlock()
resetTime := time.Now().Add(time.Duration(float64(time.Second) / rate))
c.Set("X-RateLimit-Limit", fmt.Sprintf("%d", rateLimit))
c.Set("X-RateLimit-Remaining", "0")
c.Set("X-RateLimit-Reset", fmt.Sprintf("%d", resetTime.Unix()))
c.Set("X-Plan", plan)
return c.Status(429).JSON(fiber.Map{
"error": "rate_limit_exceeded",
"message": fmt.Sprintf("Rate limit of %d requests/minute exceeded for %s plan.", rateLimit, planCfg.Name),
"plan": plan,
"limit": rateLimit,
"retry_after": fmt.Sprintf("%.1fs", 1.0/rate),
"upgrade_url": "/pricing",
})
}
b.tokens--
remaining = int(b.tokens)
pm.mu.Unlock()
// Set rate limit headers
resetTime := time.Now().Add(time.Minute)
c.Set("X-RateLimit-Limit", fmt.Sprintf("%d", rateLimit))
c.Set("X-RateLimit-Remaining", fmt.Sprintf("%d", remaining))
c.Set("X-RateLimit-Reset", fmt.Sprintf("%d", resetTime.Unix()))
c.Set("X-Plan", plan)
startTime := time.Now()
err := c.Next()
// Async usage tracking
if keyRecord != nil {
go func(ak *db.APIKey, endpoint string, status int, latency int, ip string) {
_ = pm.database.IncrementUsage(ak.ID, endpoint, status, latency, ip)
}(keyRecord, path, c.Response().StatusCode(), int(time.Since(startTime).Milliseconds()), c.IP())
}
return err
}
func isEndpointAllowed(path string, allowed []string) bool {
for _, prefix := range allowed {
if strings.HasPrefix(path, prefix) {
return true
}
}
return false
}

10
internal/api/routes.go
View File

@@ -11,19 +11,28 @@ func RegisterRoutes(app *fiber.App, database *db.DB) {
h := handlers.New(database)
app.Get("/health", h.Health)
app.Get("/pricing", h.PricingPage)
v1 := app.Group("/api/v1")
// Plans endpoints (accessible to all)
v1.Get("/plans", h.ListPlans)
v1.Get("/plans/usage", h.PlanUsage)
v1.Post("/plans/register", h.RegisterPlan)
// Companies
v1.Get("/companies", h.ListCompanies)
v1.Get("/companies/search", h.SearchCompanies)
v1.Get("/companies/:id", h.GetCompany)
v1.Get("/companies/:id/filings", h.CompanyFilings)
// Filings
v1.Get("/filings", h.ListFilings)
v1.Get("/filings/search", h.SearchFilings)
v1.Get("/filings/recent", h.RecentFilings)
v1.Get("/filings/:id", h.GetFiling)
// Market
v1.Get("/market/selic", h.ListSelic)
v1.Get("/market/selic/current", h.CurrentSelic)
v1.Get("/market/cdi", h.ListCDI)
@@ -34,5 +43,6 @@ func RegisterRoutes(app *fiber.App, database *db.DB) {
v1.Get("/market/fx/current", h.CurrentFX)
v1.Get("/market/overview", h.MarketOverview)
// Search
v1.Get("/search", h.GlobalSearch)
}

7
internal/api/server.go
View File

@@ -21,11 +21,8 @@ func NewServer(cfg *config.Config, database *db.DB) *fiber.App {
app.Use(cors.New())
RegisterSwagger(app)
app.Use(middleware.NewRateLimiter(cfg.RateLimit))
if cfg.APIKey != "" {
app.Use(middleware.NewAPIKeyAuth(cfg.APIKey))
}
// Plan-based rate limiting and access control (replaces old rate limiter + API key auth)
app.Use(middleware.NewPlanMiddleware(database))
RegisterRoutes(app, database)