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

- 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

internal/api/docs/openapi.yaml

@@ -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