spectra-server 1.0.0__py3-none-any.whl

spectra/__init__.py

@@ -0,0 +1,35 @@
+"""Spectra analytics ingestion server.
+
+Quickstart
+----------
+Install the package and run the built-in CLI::
+
+    pip install spectra-server
+    spectra-server
+
+Custom middleware / extending the server
+-----------------------------------------
+Use :func:`create_app` to obtain a FastAPI instance with your own middleware
+injected before running it::
+
+    # myapp.py
+    from spectra import create_app
+    from my_auth import APIKeyMiddleware
+
+    app = create_app(
+        middleware=[
+            (APIKeyMiddleware, {"header": "X-API-Key", "keys": ["sk-..."]}),
+        ]
+    )
+
+Then point uvicorn at your module::
+
+    uvicorn myapp:app --host 0.0.0.0 --port 8000
+"""
+
+from spectra.app import create_app
+from fastapi import FastAPI
+
+app: FastAPI = create_app()
+
+__all__ = ["app", "create_app"]

spectra/app.py

@@ -0,0 +1,144 @@
+"""Factory for the Spectra FastAPI application.
+
+Developers who want to extend the server can call :func:`create_app` and
+inject their own middleware (e.g. API-key validation, rate limiting, auth):
+
+.. code-block:: python
+
+    from spectra import create_app
+    from my_auth import APIKeyMiddleware
+
+    app = create_app(
+        middleware=[
+            (APIKeyMiddleware, {"header": "X-API-Key", "keys": ["sk-..."]}),
+        ]
+    )
+
+Then run with ``uvicorn mymodule:app``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import ValidationError
+
+from spectra.bigquery_client import insert_events
+from spectra.config import CORS_ORIGINS, bigquery_configured
+from spectra.events import Event
+
+_MiddlewareEntry = tuple[type[Any], dict[str, Any]]
+
+
+def create_app(
+    *,
+    cors_origins: list[str] | None = None,
+    middleware: list[_MiddlewareEntry] | None = None,
+    **fastapi_kwargs: Any,
+) -> FastAPI:
+    """Create and return a configured Spectra FastAPI application.
+
+    Args:
+        cors_origins: List of allowed CORS origins. Defaults to the
+            ``CORS_ORIGINS`` environment variable (``*`` if unset).
+        middleware: Additional Starlette/FastAPI middleware to mount, each
+            expressed as ``(MiddlewareClass, kwargs_dict)``. Middleware is
+            applied in the order given (i.e. the first entry is the outermost
+            layer). CORS middleware is always added before any custom entries.
+        **fastapi_kwargs: Extra keyword arguments forwarded to
+            :class:`fastapi.FastAPI` (e.g. ``title``, ``docs_url``).
+    """
+    fastapi_kwargs.setdefault("title", "Spectra JS")
+    fastapi_kwargs.setdefault("description", "Event ingestion API for Spectra JS")
+
+    app = FastAPI(**fastapi_kwargs)
+
+    origins = cors_origins if cors_origins is not None else CORS_ORIGINS
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=origins if origins != ["*"] else ["*"],
+        allow_credentials=False,
+        allow_methods=["GET", "POST", "OPTIONS"],
+        allow_headers=["*"],
+    )
+
+    # Starlette applies middleware in reverse registration order (last added =
+    # outermost). To preserve the intuitive "first entry = outermost" contract
+    # we reverse the list before adding.
+    for cls, kwargs in reversed(middleware or []):
+        app.add_middleware(cls, **kwargs)
+
+    @app.post("/track")
+    async def ingest_events(request: Request) -> dict[str, Any]:
+        """Ingest events and store them in BigQuery.
+
+        Payload: ``{ account_id?: string, events: [...] }``
+
+        ``account_id`` can be provided via the ``X-Account-ID`` header or in
+        the request body.  Accepts ``application/json`` or ``text/plain``
+        (the latter avoids a CORS preflight for ``navigator.sendBeacon``
+        requests).
+        """
+        header_account_id = (request.headers.get("X-Account-ID") or "").strip() or None
+        body_bytes = await request.body()
+        try:
+            payload = json.loads(body_bytes)
+        except json.JSONDecodeError as e:
+            raise HTTPException(status_code=400, detail=f"Invalid JSON: {e}") from e
+        if not isinstance(payload, dict):
+            raise HTTPException(status_code=400, detail="Expected object with 'events' array")
+        raw_events = payload.get("events")
+        if not isinstance(raw_events, list):
+            raise HTTPException(status_code=400, detail="Expected 'events' array")
+
+        account_id = header_account_id or (payload.get("account_id") or "").strip() or None
+
+        events: list[Event] = []
+        for i, item in enumerate(raw_events):
+            try:
+                events.append(Event.model_validate(item))
+            except ValidationError as e:
+                raise HTTPException(
+                    status_code=400, detail={"index": i, "errors": e.errors()}
+                ) from e
+
+        if not events:
+            return {"status": "ok", "count": 0}
+
+        if bigquery_configured() and not account_id:
+            raise HTTPException(status_code=400, detail="X-Account-ID header is required")
+
+        if not bigquery_configured():
+            return {
+                "status": "ok",
+                "message": "BigQuery not configured; events discarded",
+                "count": len(events),
+            }
+
+        def _log_insert_error(task: asyncio.Task[None]) -> None:
+            try:
+                task.result()
+            except Exception as exc:
+                logging.getLogger(__name__).exception(
+                    "Background BigQuery insert failed: %s", exc
+                )
+
+        task = asyncio.create_task(asyncio.to_thread(insert_events, events, account_id))
+        task.add_done_callback(_log_insert_error)
+
+        return {"status": "ok", "count": len(events)}
+
+    @app.get("/health")
+    async def health() -> dict[str, str]:
+        """Health check endpoint."""
+        return {
+            "status": "ok",
+            "bigquery": "configured" if bigquery_configured() else "not_configured",
+        }
+
+    return app

spectra/bigquery_client.py

@@ -0,0 +1,120 @@
+"""BigQuery client for inserting analytics events."""
+import base64
+import json
+import os
+import re
+
+# Adding a Pyright ignore for the unresolved import.
+# The venv lacks dependencies on local (pip install failed due to SSL),
+# so the linter can't resolve the package.
+import google.cloud.bigquery as bigquery  # pyright: ignore[reportMissingImports]
+from google.oauth2 import credentials  # pyright: ignore[reportMissingImports]
+from google.oauth2 import service_account  # pyright: ignore[reportMissingImports]
+
+from spectra.config import BIGQUERY_DATASET, BIGQUERY_PROJECT_ID
+from spectra.events import Event, event_to_row
+
+
+def _get_credentials():
+    """Return credentials from GOOGLE_APPLICATION_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS_JSON."""
+    if os.environ.get("GOOGLE_APPLICATION_CREDENTIALS"):
+        return None  # Let ADC use the file path
+    json_b64 = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS_JSON")
+    if json_b64:
+        info = json.loads(base64.b64decode(json_b64).decode("utf-8"))
+        if info.get("type") == "authorized_user":
+            return credentials.Credentials(
+                token=None,
+                refresh_token=info.get("refresh_token"),
+                token_uri="https://oauth2.googleapis.com/token",
+                client_id=info.get("client_id"),
+                client_secret=info.get("client_secret"),
+            )
+        return service_account.Credentials.from_service_account_info(info)
+    return None
+
+
+_client: bigquery.Client | None = None
+_ACCOUNT_ID_RE = re.compile(r"^[A-Za-z0-9_]+$")
+
+
+def get_client() -> bigquery.Client:
+    """Return a cached BigQuery client (thread-safe for inserts)."""
+    global _client
+    if _client is None:
+        creds = _get_credentials()
+        kwargs: dict = {"project": BIGQUERY_PROJECT_ID or ""}
+        if creds is not None:
+            kwargs["credentials"] = creds
+        _client = bigquery.Client(**kwargs)
+    return _client
+
+
+def insert_events(events: list[Event], account_id: str | None = None) -> None:
+    """Insert an array of events into BigQuery. Table is determined by account_id header (required)."""
+    if not events:
+        return
+    if not account_id:
+        raise ValueError("account_id header is required")
+    if not BIGQUERY_PROJECT_ID or not BIGQUERY_DATASET:
+        raise ValueError("BigQuery is not configured")
+    client = get_client()
+
+    table_id = f"{BIGQUERY_PROJECT_ID}.{BIGQUERY_DATASET}.{account_id}"
+    rows = [event_to_row(e.model_copy(update={"account_id": account_id})) for e in events]
+    errors = client.insert_rows_json(table_id, rows)
+    if errors:
+        raise RuntimeError(f"BigQuery insert failed: {errors}")
+
+
+def fetch_events(account_id: str, limit: int = 1000) -> list[dict]:
+    """
+    Fetch recent analytics events for a given account table.
+    Table is resolved as BIGQUERY_PROJECT_ID.BIGQUERY_DATASET.<account_id>.
+    """
+    if not account_id:
+        raise ValueError("account_id is required")
+    if not _ACCOUNT_ID_RE.fullmatch(account_id):
+        raise ValueError("account_id may only contain letters, numbers, and underscores")
+    if limit <= 0:
+        raise ValueError("limit must be greater than 0")
+    if not BIGQUERY_PROJECT_ID or not BIGQUERY_DATASET:
+        raise ValueError("BigQuery is not configured")
+
+    client = get_client()
+    table_id = f"{BIGQUERY_PROJECT_ID}.{BIGQUERY_DATASET}.{account_id}"
+    query = (
+        f"SELECT * FROM `{table_id}` "
+        "ORDER BY event_timestamp DESC "
+        "LIMIT @limit"
+    )
+    job_config = bigquery.QueryJobConfig(
+        query_parameters=[
+            bigquery.ScalarQueryParameter("limit", "INT64", limit),
+        ]
+    )
+    rows = client.query(query, job_config=job_config).result()
+    return [dict(row.items()) for row in rows]
+
+
+def fetch_all_events(limit: int = 5000) -> list[dict]:
+    """Fetch recent analytics events across all account tables in the dataset."""
+    if limit <= 0:
+        raise ValueError("limit must be greater than 0")
+    if not BIGQUERY_PROJECT_ID or not BIGQUERY_DATASET:
+        raise ValueError("BigQuery is not configured")
+
+    client = get_client()
+    wildcard_table = f"{BIGQUERY_PROJECT_ID}.{BIGQUERY_DATASET}.*"
+    query = (
+        f"SELECT * FROM `{wildcard_table}` "
+        "ORDER BY event_timestamp DESC "
+        "LIMIT @limit"
+    )
+    job_config = bigquery.QueryJobConfig(
+        query_parameters=[
+            bigquery.ScalarQueryParameter("limit", "INT64", limit),
+        ]
+    )
+    rows = client.query(query, job_config=job_config).result()
+    return [dict(row.items()) for row in rows]

spectra/cli.py

@@ -0,0 +1,67 @@
+"""Command-line entry point for the Spectra server.
+
+Installed as the ``spectra-server`` script via ``[project.scripts]``.
+
+Usage::
+
+    spectra-server
+    spectra-server --host 0.0.0.0 --port 8080
+    spectra-server --reload
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from spectra.config import HOST, PORT
+
+
+def main() -> None:
+    """Parse arguments and start the uvicorn server."""
+    parser = argparse.ArgumentParser(
+        prog="spectra-server",
+        description="Run the Spectra event ingestion server.",
+    )
+    parser.add_argument(
+        "--host",
+        default=HOST,
+        help=f"Bind host (default: {HOST}, override with HOST env var)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=PORT,
+        help=f"Bind port (default: {PORT}, override with PORT env var)",
+    )
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        default=False,
+        help="Enable auto-reload (development only)",
+    )
+    parser.add_argument(
+        "--workers",
+        type=int,
+        default=1,
+        help="Number of worker processes (default: 1, incompatible with --reload)",
+    )
+    args = parser.parse_args()
+
+    try:
+        import uvicorn
+    except ImportError:
+        print("uvicorn is required. Install it with: pip install uvicorn[standard]", file=sys.stderr)
+        sys.exit(1)
+
+    uvicorn.run(
+        "spectra:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+        workers=args.workers if not args.reload else 1,
+    )
+
+
+if __name__ == "__main__":
+    main()

spectra/config.py

@@ -0,0 +1,35 @@
+"""Server configuration from environment variables."""
+
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def _require(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise ValueError(f"Required environment variable {name} is not set")
+    return value
+
+
+def _opt(name: str, default: str = "") -> str:
+    return os.environ.get(name, default)
+
+
+# BigQuery
+BIGQUERY_PROJECT_ID = _opt("BIGQUERY_PROJECT_ID")
+BIGQUERY_DATASET = _opt("BIGQUERY_DATASET")
+
+# Server
+HOST = _opt("HOST", "0.0.0.0")
+PORT = int(_opt("PORT", "8000"))
+
+# CORS (comma-separated origins, or * for all)
+CORS_ORIGINS = _opt("CORS_ORIGINS", "*").split(",")
+
+
+def bigquery_configured() -> bool:
+    """Return True if BigQuery is fully configured."""
+    return bool(BIGQUERY_PROJECT_ID and BIGQUERY_DATASET)

spectra/events.py

@@ -0,0 +1,97 @@
+"""Event models and BigQuery ingestion."""
+
+from pydantic import BaseModel
+
+
+class Event(BaseModel):
+    """Analytics event - aligned with planning/events.md schema."""
+
+    # Base (required)
+    event_id: str
+    event_timestamp: str
+    event_name: str
+    session_id: str
+
+    # Base (optional)
+    page_url: str | None = None
+    user_agent: str | None = None
+    spectra_version: str | None = None
+    account_id: str | None = None
+
+    # 1. Page Context
+    page_title: str | None = None
+    page_path: str | None = None
+    page_hostname: str | None = None
+    referrer: str | None = None
+    referrer_domain: str | None = None
+    previous_page_url: str | None = None
+    page_type: str | None = None
+    canonical_url: str | None = None
+    language: str | None = None
+
+    # 2. User Context
+    user_id: str | None = None
+    anonymous_id: str | None = None
+    user_type: str | None = None
+
+    # 3. Traffic & Attribution
+    utm_source: str | None = None
+    utm_medium: str | None = None
+    utm_campaign: str | None = None
+    utm_term: str | None = None
+    utm_content: str | None = None
+    gclid: str | None = None
+    fbclid: str | None = None
+    ttclid: str | None = None
+    traffic_source: str | None = None
+    traffic_medium: str | None = None
+    campaign_id: str | None = None
+    ad_group_id: str | None = None
+    creative_id: str | None = None
+    landing_page: str | None = None
+    first_touch_source: str | None = None
+    first_touch_medium: str | None = None
+    first_touch_campaign: str | None = None
+
+    # 4. Device & Technical
+    device_type: str | None = None
+    browser: str | None = None
+    browser_version: str | None = None
+    operating_system: str | None = None
+    os_version: str | None = None
+    screen_resolution: str | None = None
+    viewport_size: str | None = None
+    timezone: str | None = None
+    connection_type: str | None = None
+
+    # 5. Timestamp & Timing
+    event_date: str | None = None
+    event_time: str | None = None
+    local_time: str | None = None
+    time_on_page: float | None = None
+
+    # Click-specific
+    element_tag: str | None = None
+    element_id: str | None = None
+    element_classes: str | None = None
+    element_text: str | None = None
+    element_href: str | None = None
+    position_x: int | None = None
+    position_y: int | None = None
+
+    # Scroll-specific
+    scroll_depth_pct: float | None = None
+    scroll_y: int | None = None
+    page_height: int | None = None
+    viewport_height: int | None = None
+
+    # Form-specific
+    form_id: str | None = None
+    form_action: str | None = None
+    form_method: str | None = None
+    field_count: int | None = None
+
+
+def event_to_row(event: Event) -> dict:
+    """Convert event to BigQuery row. None stays as null."""
+    return event.model_dump()

spectra_server-1.0.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: spectra-server
+Version: 1.0.0
+Summary: Analytics event ingestion server for Spectra
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: google-cloud-bigquery>=3.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# spectra-server
+
+The Spectra event ingestion server. Receives analytics events from the [Spectra tracker script](../script/README.md) and writes them to Google BigQuery.
+
+Built with [FastAPI](https://fastapi.tiangolo.com/) and [Pydantic](https://docs.pydantic.dev/).
+
+## Installation
+
+```bash
+pip install spectra-server
+```
+
+Requires Python 3.11+.
+
+## Running the server
+
+### Option A — CLI (quickest)
+
+Set the required environment variables (see [Configuration](#configuration)), then:
+
+```bash
+spectra-server
+```
+
+Available flags:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--host` | `0.0.0.0` | Bind host (overrides `HOST` env var) |
+| `--port` | `8000` | Bind port (overrides `PORT` env var) |
+| `--reload` | off | Enable auto-reload (development only) |
+| `--workers` | `1` | Number of worker processes |
+
+### Option B — uvicorn directly
+
+```bash
+uvicorn spectra:app --host 0.0.0.0 --port 8000
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and fill in the values. The server reads configuration from environment variables (loaded via `python-dotenv`):
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BIGQUERY_PROJECT_ID` | Yes (for storage) | GCP project ID |
+| `BIGQUERY_DATASET` | Yes (for storage) | BigQuery dataset name |
+| `GOOGLE_APPLICATION_CREDENTIALS` | One of the two | Path to a service account JSON file |
+| `GOOGLE_APPLICATION_CREDENTIALS_JSON` | One of the two | Base64-encoded service account JSON |
+| `HOST` | No | Bind host (default: `0.0.0.0`) |
+| `PORT` | No | Bind port (default: `8000`) |
+| `CORS_ORIGINS` | No | Comma-separated allowed origins, or `*` (default: `*`) |
+
+If neither BigQuery variable is set the server starts successfully and discards events — useful for local development without a GCP project.
+
+## API
+
+### `POST /track`
+
+Ingest one or more events.
+
+**Headers**
+
+| Header | Description |
+|--------|-------------|
+| `X-Account-ID` | Tenant / BigQuery table name. Can also be passed in the request body. |
+| `Content-Type` | `application/json` or `text/plain` (plain text avoids CORS preflight for `navigator.sendBeacon`) |
+
+**Body**
+
+```json
+{
+  "account_id": "optional_if_provided_in_header",
+  "events": [
+    { "name": "page_view", "timestamp": "2024-01-01T00:00:00Z", "properties": {} }
+  ]
+}
+```
+
+**Response**
+
+```json
+{ "status": "ok", "count": 2 }
+```
+
+### `GET /health`
+
+Returns server status and whether BigQuery is configured.
+
+```json
+{ "status": "ok", "bigquery": "configured" }
+```
+
+## Extending the server
+
+The `create_app()` factory lets you mount your own middleware — API key validation, rate limiting, authentication, request logging, etc. — without forking the codebase.
+
+### Adding middleware
+
+```python
+# myapp.py
+from spectra import create_app
+from my_auth import APIKeyMiddleware
+
+app = create_app(
+    middleware=[
+        (APIKeyMiddleware, {"header": "X-API-Key", "keys": ["sk-live-..."]}),
+    ]
+)
+```
+
+Then run it:
+
+```bash
+uvicorn myapp:app --host 0.0.0.0 --port 8000
+```
+
+Middleware entries are `(MiddlewareClass, kwargs_dict)` tuples. The first entry in the list is the outermost layer (runs first on incoming requests).
+
+### API key validation example
+
+Here is a minimal Starlette middleware that validates a bearer token:
+
+```python
+# auth.py
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+class APIKeyMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, *, keys: list[str], header: str = "Authorization"):
+        super().__init__(app)
+        self.keys = set(keys)
+        self.header = header
+
+    async def dispatch(self, request: Request, call_next):
+        if request.url.path == "/health":
+            return await call_next(request)
+        token = request.headers.get(self.header, "").removeprefix("Bearer ").strip()
+        if token not in self.keys:
+            return JSONResponse({"detail": "Unauthorized"}, status_code=401)
+        return await call_next(request)
+```
+
+```python
+# myapp.py
+from spectra import create_app
+from auth import APIKeyMiddleware
+
+app = create_app(
+    middleware=[
+        (APIKeyMiddleware, {"keys": ["sk-live-abc123"], "header": "Authorization"}),
+    ]
+)
+```
+
+### Overriding FastAPI settings
+
+Any keyword argument not recognised by `create_app` is forwarded to `FastAPI()`:
+
+```python
+app = create_app(
+    cors_origins=["https://myapp.com"],
+    docs_url=None,      # disable Swagger UI in production
+    redoc_url=None,
+)
+```
+
+## Local development
+
+```bash
+git clone https://github.com/mvallejo3/spectra.git
+cd spectra/server
+
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+cp .env.example .env  # fill in your values
+
+make start            # uvicorn app:app --reload
+```
+
+## License
+
+[MIT](../LICENSE)

spectra_server-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+spectra/__init__.py,sha256=w9UXdw2MkV2cE_QzyrPqqAUR_-MGi9OBaTcXgVTUuag,796
+spectra/app.py,sha256=PJCP3tu1bctW-LpLkayhqbE46LziZCST_Mz78idDAG0,5203
+spectra/bigquery_client.py,sha256=puRjlhjfqpWfyJspsJR-bAU7xBTINNrHwMwFm3FNjl0,4599
+spectra/cli.py,sha256=iLWtNDrma5HxZ0PIucVCWcoFiX6iuOl6XsyZZjaDH2U,1614
+spectra/config.py,sha256=1QG5b5xqY0z-XNA0jsZEhBkGf56wl0f0xDqw6h8JTH8,813
+spectra/events.py,sha256=qdLNtvSlB8I8Oca1wrqK4Uw51_LOw-0MmQt0t5yHLkM,2795
+spectra_server-1.0.0.dist-info/METADATA,sha256=JDcsQKrGNX5p2SkkOPzMwF5IrJpDiH011ATo3CWjkWU,5270
+spectra_server-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+spectra_server-1.0.0.dist-info/entry_points.txt,sha256=O4-OXhX_TporNNeKgcgaoLDkyVmD-8J1QnVK4pww9wo,52
+spectra_server-1.0.0.dist-info/RECORD,,

spectra_server-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

spectra_server-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spectra-server = spectra.cli:main