Skip to content

SDK Overview

The SPOT Contracts repository provides SDKs for Python and TypeScript, automatically generated from OpenAPI specifications.

Available SDKs

Python SDK

  • Package: spot-sdk
  • Language: Python 3.11+
  • Framework: Pydantic v2
  • Registry: GitLab PyPI

View Python SDK Documentation →

TypeScript SDK

  • Package: @spot/contracts
  • Language: TypeScript 5.3+
  • Framework: Axios
  • Registry: GitLab NPM

View TypeScript SDK Documentation →

Quick Installation

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

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

Quick Start

from spot_sdk.api_gateway import Email, EmailHeader
from spot_sdk.api_gateway import AnalysisResult

# Create email
email = Email(
    id="test-123",
    headers=EmailHeader(
        subject="Test email",
        sender="test@example.com",
        recipients=["user@company.com"]
    ),
    body_text="Email content"
)

# Use in your analyzer
result = AnalysisResult(
    is_phishing=False,
    threat_level="safe",
    confidence=0.1,
    explanation="No threats detected",
    indicators=[],
    metadata=AnalysisMetadata(...)
)

import { Email, EmailHeader, AnalysisResult } from '@spot/contracts';

// Create email
const email: Email = {
  id: 'test-123',
  headers: {
    subject: 'Test email',
    sender: 'test@example.com',
    recipients: ['user@company.com']
  },
  body_text: 'Email content'
};

// Use in your application
const result: AnalysisResult = {
  is_phishing: false,
  threat_level: 'safe',
  confidence: 0.1,
  explanation: 'No threats detected',
  indicators: [],
  metadata: {...}
};

Common Models

Both SDKs provide the same core models:

Email Models

  • Email - Complete email structure
  • EmailHeader - Email headers and metadata
  • Attachment - File attachments

Analysis Models

  • AnalysisResult - Analysis outcome
  • AnalysisIndicator - Spear-phishing indicators
  • AnalysisMetadata - Analysis metadata
  • ThreatLevel - Threat severity enum
  • IndicatorType - Indicator type enum

Workflow Models

  • Workflow - Workflow definition
  • WorkflowStage - Workflow stage configuration
  • AnalyzerConfig - Analyzer configuration

Orchestrator Models

  • OrchestrationResult - Overall analysis result
  • AnalyzerResult - Individual analyzer result
  • WorkflowStageResult - Stage execution result

SDK Generation

SDKs are automatically generated from OpenAPI specifications:

# Validate OpenAPI specs
make validate

# Generate both SDKs
make generate

# Generate specific SDK
make generate-python
make generate-typescript

Generation Flow

OpenAPI Specs (openapi/*.yaml)
        ↓
    Validation
        ↓
    Generation Tools
    ├── datamodel-code-generator (Python)
    └── openapi-typescript-codegen (TypeScript)
        ↓
    Generated SDKs (sdk/)
        ↓
    Testing & Validation
        ↓
    Publishing (GitLab Registries)

Version Management

Python and TypeScript SDKs have independent versions:

# Check versions
make check-versions

# Bump versions
make bump-python VERSION=1.2.0
make bump-typescript VERSION=2.1.0

Publishing

SDKs are published automatically via GitLab CI when tags are created:

# Publish Python SDK
git tag python-v1.2.0
git push origin python-v1.2.0

# Publish TypeScript SDK
git tag typescript-v2.1.0
git push origin typescript-v2.1.0

See Publishing Guide for detailed publishing instructions.

Use Cases

For Analyzer Developers

Use the SDK to implement SPOT analyzers: 

from spot_sdk.api_gateway import Email
from spot_sdk.api_gateway import AnalysisResult

@app.post("/internal/analyze")
async def analyze(email: Email) -> AnalysisResult:
    # Your analysis logic
    return AnalysisResult(...)

For Application Developers

Use the SDK to integrate with SPOT Platform: 

import { SpotApiClient } from './client';
import { Email } from '@spot/contracts';

const client = new SpotApiClient();
const result = await client.analyzeEmail(email);

For Testing

Use the SDK models in tests: 

from spot_sdk.api_gateway import Email

def test_email_validation():
    email = Email(id="test", headers=...)
    assert email.id == "test"

Next Steps

Support