Skip to content

SPOT Contracts Documentation

Single source of truth for all SPOT Platform API contracts and generated SDKs.

This repository centralizes OpenAPI specifications and Python interface definitions for the entire SPOT ecosystem, automatically generating and publishing SDKs for Python and TypeScript with comprehensive documentation.

Quick Start

# Build docker containers
make build

# Validate OpenAPI specifications
make validate

# Generate both SDKs
make generate

# Run comprehensive tests
make test

# Generate documentation site
make docs

# See full list of commands
make help

Core Features

  • Automated SDK Generation - Python and TypeScript SDKs from OpenAPI specs
  • Private Registry Publishing - GitLab PyPI and NPM registries
  • Docker-First Development - No local dependencies required
  • Interactive Documentation - API specs with Swagger UI integration

Architecture

The SPOT Contracts repository follows a simple architecture:

spot-sdk/
├── docs/                 # Documentation (this directory)
├── openapi/              # OpenAPI 3.0 specifications
│   └── api-gateway.yaml  # Unified API Gateway
├── interfaces/           # Python interface models (Pydantic v2)
│   ├── email.py          # Email data models
│   ├── analyzer.py       # Analyzer interfaces
│   └── results.py        # Analysis result models
├── sdk/                  # Generated SDKs
│   ├── python/           # Python SDK with Poetry
│   └── typescript/       # TypeScript SDK with NPM
├── tests/                # Contract validation tests (97%+ coverage)
└── scripts/              # Automation scripts

Available Commands

Command Description
Development
make help Show all available commands with descriptions
make validate Validate OpenAPI specifications
make generate Generate both Python and TypeScript SDKs
make test Run contract validation tests (Docker-based)
make shell Enter interactive development container
Documentation
make docs Generate complete documentation site
make docs-serve Serve documentation locally on port 8005
Publishing
make publish-python Publish Python SDK to GitLab Registry
make publish-typescript Publish TypeScript SDK to GitLab Registry

Environment Configuration

Create .env file for local development:

# Copy example configuration
cp .env.example .env

# Configure your GitLab settings

CI_PROJECT_ID=303
GITLAB_TOKEN=glpat-your-token-here
GITLAB_CA_CERT=certs/gitlab-ca.crt  # For private GitLab instances

Getting Started

For SDK Users

Install the SDK in your project:

pip install spot-sdk \
  --index-url https://pypi.org/simple/

npm config set @spot:registry https://registry.npmjs.org/
npm install @spot/contracts

See SDK Overview for complete usage examples.

For Analyzer Developers

Build custom analyzers for the SPOT platform:

from fastapi import FastAPI
from spot_sdk.api_gateway import Email
from spot_sdk.api_gateway import AnalysisResult, AnalysisMetadata

app = FastAPI(title="My Analyzer")

@app.post("/internal/analyze")
async def analyze(email: Email) -> AnalysisResult:
    # Your analysis logic here
    return AnalysisResult(
        is_phishing=False,
        threat_level="safe",
        confidence=0.5,
        explanation="Analysis completed",
        indicators=[],
        metadata=AnalysisMetadata(
            analyzer_id="my-analyzer",
            analyzer_version="1.0.0",
            analysis_duration_ms=100
        )
    )

See Analyzer Development for complete guide.

For Contributors

Development workflow:

  1. Update OpenAPI specs in openapi/ directory
  2. Validate changes: make validate
  3. Generate SDKs: make generate
  4. Run tests: make test
  5. Generate docs: make docs
  6. Preview locally: make docs-serve
  7. Commit changes

See Development Guide for detailed workflow.

Support

SPOT Project | Last Updated: 2025-11-06