spectra-server 1.0.0__tar.gz

spectra_server-1.0.0/.env.example

@@ -0,0 +1,14 @@
+# BigQuery (required for event storage; table name = event.account_id)
+BIGQUERY_PROJECT_ID=your-gcp-project
+BIGQUERY_DATASET=analytics
+
+# Server
+HOST=0.0.0.0
+PORT=8000
+
+# CORS - comma-separated origins, or * for all
+CORS_ORIGINS=*
+
+# Google Auth (for BigQuery) - one of:
+# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+# GOOGLE_APPLICATION_CREDENTIALS_JSON=base64-encoded-service-account-json (used when GOOGLE_APPLICATION_CREDENTIALS is not set)

spectra_server-1.0.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.sqlite/
+
+# Node / TypeScript
+.npmrc
+node_modules/
+dist/
+*.tsbuildinfo
+
+# Env & secrets
+.env
+.env.local
+secrets/
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+
+# Logs
+*.log
+
+# Testing
+tests/
+
+# AI 
+.cursor/
+planning/

spectra_server-1.0.0/Makefile

@@ -0,0 +1,4 @@
+.PHONY: start
+
+start:
+	uvicorn app:app --reload --host 0.0.0.0 --port 8000

spectra_server-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,185 @@
+# 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/app.py

@@ -0,0 +1,18 @@
+"""Local development entry point.
+
+This module re-exports the default ``app`` instance from the ``spectra``
+package so that the Makefile target ``uvicorn app:app`` continues to work
+without modification.
+
+For production or custom deployments, import from the package directly::
+
+    from spectra import app           # default instance
+    from spectra import create_app    # factory for custom middleware
+"""
+
+from spectra import app  # noqa: F401
+from spectra.config import HOST, PORT
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host=HOST, port=PORT)

spectra_server-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "spectra-server"
+version = "1.0.0"
+description = "Analytics event ingestion server for Spectra"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.104.0",
+    "python-dotenv>=1.0.0",
+    "google-cloud-bigquery>=3.0.0",
+    "uvicorn[standard]>=0.24.0",
+    "pydantic>=2.0.0",
+]
+
+[project.scripts]
+spectra-server = "spectra.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["spectra"]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.0.0",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true

spectra_server-1.0.0/pyrightconfig.json

@@ -0,0 +1,9 @@
+{
+  "venvPath": ".",
+  "venv": ".venv",
+  "include": ["spectra"],
+  "pythonVersion": "3.11",
+  "typeCheckingMode": "basic",
+  "reportMissingImports": true,
+  "reportMissingTypeStubs": false
+}

spectra_server-1.0.0/requirements.txt

@@ -0,0 +1,5 @@
+fastapi>=0.104.0
+google-cloud-bigquery>=3.0.0
+uvicorn[standard]>=0.24.0
+pydantic>=2.0.0
+python-dotenv>=1.0.0

spectra_server-1.0.0/schema.sql

@@ -0,0 +1,80 @@
+-- BigQuery table schema for Spectra analytics events
+-- Aligned with planning/events.md. Run in BigQuery (replace dataset as needed).
+
+CREATE TABLE IF NOT EXISTS `analytics.events` (
+  -- Base (required)
+  event_id STRING NOT NULL,
+  event_timestamp TIMESTAMP NOT NULL,
+  event_name STRING NOT NULL,
+  session_id STRING NOT NULL,
+  -- Base (optional)
+  page_url STRING,
+  user_agent STRING,
+  spectra_version STRING,
+  account_id STRING,
+  -- 1. Page Context
+  page_title STRING,
+  page_path STRING,
+  page_hostname STRING,
+  referrer STRING,
+  referrer_domain STRING,
+  previous_page_url STRING,
+  page_type STRING,
+  canonical_url STRING,
+  language STRING,
+  -- 2. User Context
+  user_id STRING,
+  anonymous_id STRING,
+  user_type STRING,
+  -- 3. Traffic & Attribution
+  utm_source STRING,
+  utm_medium STRING,
+  utm_campaign STRING,
+  utm_term STRING,
+  utm_content STRING,
+  gclid STRING,
+  fbclid STRING,
+  ttclid STRING,
+  traffic_source STRING,
+  traffic_medium STRING,
+  campaign_id STRING,
+  ad_group_id STRING,
+  creative_id STRING,
+  landing_page STRING,
+  first_touch_source STRING,
+  first_touch_medium STRING,
+  first_touch_campaign STRING,
+  -- 4. Device & Technical
+  device_type STRING,
+  browser STRING,
+  browser_version STRING,
+  operating_system STRING,
+  os_version STRING,
+  screen_resolution STRING,
+  viewport_size STRING,
+  timezone STRING,
+  connection_type STRING,
+  -- 5. Timestamp & Timing
+  event_date STRING,
+  event_time STRING,
+  local_time STRING,
+  time_on_page FLOAT64,
+  -- Click
+  element_tag STRING,
+  element_id STRING,
+  element_classes STRING,
+  element_text STRING,
+  element_href STRING,
+  position_x INT64,
+  position_y INT64,
+  -- Scroll
+  scroll_depth_pct FLOAT64,
+  scroll_y INT64,
+  page_height INT64,
+  viewport_height INT64,
+  -- Form
+  form_id STRING,
+  form_action STRING,
+  form_method STRING,
+  field_count INT64
+);

spectra_server-1.0.0/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_server-1.0.0/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_server-1.0.0/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_server-1.0.0/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_server-1.0.0/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_server-1.0.0/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()